fix(toc): stabilize scroll spy and TOC list viewport

Track only heading nodes for active-section state, keep the document
title outside the list scroller so alignment math matches the visible
list, and tighten focus rail behavior for parent rows.

Made-with: Cursor

Author: HMarzban

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

@@ -1,7 +1,8 @@
 import TableOfContentsLoader from '@components/skeleton/TableOfContentsLoader'
-import { TocDesktop } from '@components/toc'
+import { TocDesktop, TocHeader } from '@components/toc'
 import { ScrollArea } from '@components/ui/ScrollArea'
 import { useStore } from '@stores'
+import { twMerge } from 'tailwind-merge'
 
 const TOC = ({ className = '' }: { className?: string }) => {
   const loading = useStore((state) => state.settings.editor.loading)
@@ -18,12 +19,12 @@ const TOC = ({ className = '' }: { className?: string }) => {
   }
 
   return (
-    <ScrollArea
-      className={`${className} tiptap__toc h-full w-full !pt-0`}
-      orientation="vertical"
-      scrollbarSize="thin">
-      <TocDesktop className="hover:overscroll-contain" />
-    </ScrollArea>
+    <div className={twMerge('tiptap__toc flex h-full min-h-0 w-full flex-col !pt-0', className)}>
+      <TocHeader variant="desktop" />
+      <ScrollArea className="min-h-0 flex-1 !pt-0" scrollbarSize="thin" hideScrollbar>
+        <TocDesktop className="hover:overscroll-contain" />
+      </ScrollArea>
+    </div>
   )
 }
 

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

@@ -1,7 +1,8 @@
 import AppendHeadingButton from '@components/pages/document/components/AppendHeadingButton'
-import { TocMobile } from '@components/toc'
+import { TocHeader, TocMobile } from '@components/toc'
 import Button from '@components/ui/Button'
 import { useModal } from '@components/ui/ModalDrawer'
+import { ScrollArea } from '@components/ui/ScrollArea'
 import { DocsPlusIcon } from '@icons'
 import { Icons } from '@icons'
 import { useSheetStore, useStore } from '@stores'
@@ -77,9 +78,12 @@ const TocModal = ({ filterModalRef: _filterModalRef }: TocModalProps) => {
           </div>
         </header>
 
-        {/* Content — scrollable TOC list */}
-        <div className="bg-base-200 flex-1 overflow-y-auto">
-          <TocMobile className="tiptap__toc w-full pb-4 !pl-2" hideAppendButton />
+        {/* Content — doc title outside scroll so list viewport matches scrollIntoView */}
+        <div className="bg-base-200 flex min-h-0 flex-1 flex-col overflow-hidden">
+          <TocHeader variant="mobile" />
+          <ScrollArea className="min-h-0 flex-1" scrollbarSize="thin" hideScrollbar>
+            <TocMobile className="tiptap__toc w-full pb-4 !pl-2" hideAppendButton />
+          </ScrollArea>
         </div>
 
         {/* Sticky footer — add heading button */}

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

@@ -8,7 +8,6 @@ import React, { useCallback, useRef, useState } from 'react'
 import { DropIndicatorPortal, pointerYCollision, tocDragModifier } from './dnd'
 import { useToc, useTocAutoScroll, useTocDrag } from './hooks'
 import { TocContextMenu } from './TocContextMenu'
-import { TocHeader } from './TocHeader'
 import { TocItemDesktop } from './TocItemDesktop'
 import { buildNestedToc } from './utils'
 
@@ -71,16 +70,11 @@ export function TocDesktop({ className = '' }: TocDesktopProps) {
   const nestedItems = buildNestedToc(items)
 
   if (!items.length) {
-    return (
-      <div className={`${className}`}>
-        <TocHeader variant="desktop" />
-      </div>
-    )
+    return <div className={className} />
   }
 
   return (
-    <div className={`${className}`} ref={contextMenuRef}>
-      <TocHeader variant="desktop" />
+    <div className={className} ref={contextMenuRef}>
       <DndContext
         sensors={sensors}
         collisionDetection={pointerYCollision}

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

@@ -48,7 +48,7 @@ export function TocHeader({ variant }: TocHeaderProps) {
 
   if (variant === 'mobile') {
     return (
-      <div className="border-base-300 bg-base-100 sticky top-0 isolate z-30 border-b">
+      <div className="border-base-300 bg-base-100 isolate z-30 shrink-0 border-b">
         <div className="group relative flex items-center justify-between py-2">
           <span className="text-base-content text-lg font-bold">{docMetadata?.title}</span>
           <button
@@ -76,7 +76,7 @@ export function TocHeader({ variant }: TocHeaderProps) {
   }
 
   return (
-    <div className="border-base-300 bg-base-200 relative sticky top-0 isolate z-30 w-full border-b pt-2 pb-1">
+    <div className="border-base-300 bg-base-200 relative isolate z-30 w-full shrink-0 border-b pt-2 pb-1">
       <div
         className={twMerge(
           `${TOC_CLASSES.headerRow} group hover:bg-base-300/50 flex cursor-pointer items-center justify-between gap-0.5 rounded-md p-1 pr-3 pl-2`,

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

@@ -2,7 +2,6 @@ import AppendHeadingButton from '@components/pages/document/components/AppendHea
 import React from 'react'
 
 import { useToc, useTocAutoScroll } from './hooks'
-import { TocHeader } from './TocHeader'
 import { TocItemMobile } from './TocItemMobile'
 import { buildNestedToc } from './utils'
 
@@ -26,7 +25,6 @@ export function TocMobile({ className = '', hideAppendButton = false }: TocMobil
 
   return (
     <div className={className}>
-      <TocHeader variant="mobile" />
       <ul className="toc__list menu my-2 p-0">
         {nestedItems.map(({ item, nodes }) => (
           <TocItemMobile key={item.id} item={item} nestedNodes={nodes} onToggle={toggleSection} />