fix: pin article outline to detail header

Author: chiimagnus

src/ui/conversations/ConversationDetailPane.tsx

@@ -79,6 +79,7 @@ export function ConversationDetailPane({
   const [outlineScrollRoot, setOutlineScrollRoot] = useState<Element | null>(null);
   const [optimisticActiveIndex, setOptimisticActiveIndex] = useState<number | null>(null);
   const [readerToolbarPortalTarget, setReaderToolbarPortalTarget] = useState<HTMLDivElement | null>(null);
+  const [readerOutlinePortalTarget, setReaderOutlinePortalTarget] = useState<HTMLDivElement | null>(null);
   const outlineEntries = useMemo(
     () => (isChatRenderer && Array.isArray(detail?.messages) ? buildChatOutlineEntries(detail.messages) : []),
     [isChatRenderer, detail?.messages],
@@ -506,6 +507,14 @@ export function ConversationDetailPane({
               />
             </div>
           ) : null}
+
+          {isArticleRenderer ? (
+            <div
+              ref={setReaderOutlinePortalTarget}
+              className="tw-absolute tw-right-3 tw-top-full tw-z-30 tw-pt-3 md:tw-right-4"
+              data-reader-outline-toolbar-slot={outlineScrollRoot ? 'route-scroll' : 'viewport'}
+            />
+          ) : null}
         </header>
 
         <div className={[containerPaddingClassName, 'tw-relative tw-pb-3 md:tw-pb-4'].join(' ')}>
@@ -520,6 +529,8 @@ export function ConversationDetailPane({
               setMessagesRootRef={setMessagesRootRef}
               readerFeatures={readerFeatures}
               readerToolbarPortalTarget={readerToolbarPortalTarget}
+              readerOutlinePortalTarget={readerOutlinePortalTarget}
+              outlineScrollRoot={outlineScrollRoot}
             />
           ) : (
             <ChatDetailView

src/ui/conversations/views/ArticleReaderView.tsx

@@ -41,6 +41,8 @@ export type ReaderFeatures = { textLayout: boolean; theme: boolean; narration: b
 export type ArticleReaderViewProps = DetailViewSharedProps & {
   readerFeatures?: ReaderFeatures;
   readerToolbarPortalTarget?: HTMLElement | null;
+  readerOutlinePortalTarget?: HTMLElement | null;
+  outlineScrollRoot?: Element | null;
 };
 
 // Body typography is driven entirely by the `--reader-*` CSS variables (P2-T3).
@@ -63,7 +65,7 @@ const READER_PROSE_CLASS = [
 const READER_COLUMN_STYLE: CSSProperties = { maxWidth: 'var(--reader-content-width)' };
 const READER_SHELL_CLASS = 'tw-flex tw-w-full tw-items-start tw-gap-4';
 const READER_MAIN_CLASS = 'tw-min-w-0 tw-flex-1 tw-max-w-full';
-const READER_RAIL_CLASS = 'tw-sticky tw-top-5 tw-flex-none tw-shrink-0 tw-self-start';
+const READER_RAIL_CLASS = 'tw-flex-none tw-shrink-0 tw-self-start';
 
 /**
  * ArticleReaderView renders article / video conversations.
@@ -84,6 +86,8 @@ export function ArticleReaderView({
   setMessagesRootRef,
   readerFeatures,
   readerToolbarPortalTarget,
+  readerOutlinePortalTarget,
+  outlineScrollRoot,
 }: ArticleReaderViewProps) {
   // readerFeatures gates each toolbar piece; chat conversations pass all-false (or
   // omit it), so the toolbar renders nothing over the chat view.
@@ -103,7 +107,7 @@ export function ArticleReaderView({
   const [narrationSource, setNarrationSource] = useState('');
   const [sentenceDomRevision, setSentenceDomRevision] = useState(0);
   const sentenceCountRef = useRef(0);
-  const outline = useArticleOutlineMinimap(outlineRoot);
+  const outline = useArticleOutlineMinimap(outlineRoot, outlineScrollRoot);
   const narration = useReaderNarration(narrationSource, prefs.tts);
   const { activeSentence } = narration;
   const isNarrationEngaged = features.narration && narration.state !== 'idle';
@@ -440,6 +444,15 @@ export function ArticleReaderView({
   }, [features, prefs, readerToolbarPortalTarget, themeMode, toolbarNarration, update, updateThemeMode]);
 
   const shouldRenderInlineRail = !!outlinePayload?.entries.length;
+  const outlineRail = outlinePayload ? (
+    <aside className={READER_RAIL_CLASS} data-reader-rail="article-rail">
+      <ReaderToolbar outline={outlinePayload} />
+    </aside>
+  ) : null;
+  const outlineToolbarPortal = useMemo(() => {
+    if (!readerOutlinePortalTarget || !outlineRail) return null;
+    return createPortal(outlineRail, readerOutlinePortalTarget);
+  }, [outlineRail, readerOutlinePortalTarget]);
 
   const handleSentenceClick = useCallback(
     (event: ReactMouseEvent<HTMLDivElement>) => {
@@ -464,6 +477,7 @@ export function ArticleReaderView({
   return (
     <>
       {headerToolbar}
+      {outlineToolbarPortal}
       <div
         className={READER_SHELL_CLASS}
         style={readerVars}
@@ -514,10 +528,8 @@ export function ArticleReaderView({
           )}
         </div>
 
-        {shouldRenderInlineRail ? (
-          <aside className={READER_RAIL_CLASS} data-reader-rail="article-rail">
-            <ReaderToolbar outline={outlinePayload} />
-          </aside>
+        {shouldRenderInlineRail && !readerOutlinePortalTarget ? (
+          outlineRail
         ) : null}
       </div>
     </>

src/ui/reader/ArticleOutlineMinimap.tsx

@@ -35,7 +35,11 @@ const STRIP_CLASS = 'tw-flex tw-flex-col tw-items-end tw-gap-2 tw-py-1 tw-pr-1';
 const PANEL_LIST_CLASS = 'tw-flex tw-max-h-[60vh] tw-flex-col tw-gap-1 tw-overflow-auto';
 const OUTLINE_REBUILD_SETTLE_MS = 180;
 
-function readViewportRect(): ReaderOutlineCandidate['rect'] {
+function readViewportRect(scrollRoot?: Element | null): ReaderOutlineCandidate['rect'] {
+  if (scrollRoot && typeof scrollRoot.getBoundingClientRect === 'function') {
+    const rect = scrollRoot.getBoundingClientRect();
+    return { top: rect.top, bottom: rect.bottom };
+  }
   const view = globalThis.window ?? null;
   const height = Number(view?.innerHeight);
   if (!Number.isFinite(height) || height <= 0) return { top: 0, bottom: 0 };
@@ -121,28 +125,34 @@ function renderOutlineItem(
   );
 }
 
-export function useArticleOutlineMinimap(root: HTMLElement | null): ArticleOutlineMinimapState {
+export function useArticleOutlineMinimap(
+  root: HTMLElement | null,
+  scrollRoot?: Element | null,
+): ArticleOutlineMinimapState {
   const [entries, setEntries] = useState<ReaderOutlineDomEntry[]>([]);
   const [activeIndex, setActiveIndex] = useState<number | null>(null);
   const entriesRef = useRef<ReaderOutlineDomEntry[]>([]);
   const activeIndexRef = useRef<number | null>(null);
   const rafRef = useRef<number | null>(null);
   const pendingKindRef = useRef<'entries' | 'active' | null>(null);
 
-  const syncActiveIndex = useCallback((currentEntries: ReaderOutlineDomEntry[] = entriesRef.current) => {
-    const candidates = readCurrentCandidates(currentEntries);
-    const nextActiveIndex = candidates.length
-      ? pickReaderOutlineActiveIndex({ viewportRect: readViewportRect(), candidates })
-      : null;
-    publishReaderPerformanceStats((current) => ({
-      ...current,
-      outlineEntries: currentEntries.length,
-      outlineActiveRecalcCount: current.outlineActiveRecalcCount + 1,
-    }));
-    if (nextActiveIndex === activeIndexRef.current) return;
-    activeIndexRef.current = nextActiveIndex;
-    setActiveIndex(nextActiveIndex);
-  }, []);
+  const syncActiveIndex = useCallback(
+    (currentEntries: ReaderOutlineDomEntry[] = entriesRef.current) => {
+      const candidates = readCurrentCandidates(currentEntries);
+      const nextActiveIndex = candidates.length
+        ? pickReaderOutlineActiveIndex({ viewportRect: readViewportRect(scrollRoot), candidates })
+        : null;
+      publishReaderPerformanceStats((current) => ({
+        ...current,
+        outlineEntries: currentEntries.length,
+        outlineActiveRecalcCount: current.outlineActiveRecalcCount + 1,
+      }));
+      if (nextActiveIndex === activeIndexRef.current) return;
+      activeIndexRef.current = nextActiveIndex;
+      setActiveIndex(nextActiveIndex);
+    },
+    [scrollRoot],
+  );
 
   const rebuild = useCallback(() => {
     if (!root) {
@@ -231,7 +241,7 @@ export function useArticleOutlineMinimap(root: HTMLElement | null): ArticleOutli
       observer.observe(root, { childList: true, subtree: true, characterData: true });
     }
 
-    const scrollTarget: EventTarget = win || root;
+    const scrollTarget: EventTarget = scrollRoot ?? win ?? root;
     scrollTarget.addEventListener?.('scroll', onScroll, { passive: true });
     win?.addEventListener?.('resize', onResize, { passive: true });
     schedule('entries');
@@ -248,7 +258,7 @@ export function useArticleOutlineMinimap(root: HTMLElement | null): ArticleOutli
       }
       pendingKindRef.current = null;
     };
-  }, [rebuild, root, syncActiveIndex]);
+  }, [rebuild, root, scrollRoot, syncActiveIndex]);
 
   return { entries, activeIndex };
 }

tests/smoke/reader-mode-regression.test.ts

@@ -267,6 +267,9 @@ describe('reader mode regression', () => {
     expect(document.querySelector('[data-reader-header-toolbar-slot="true"]')).toBeTruthy();
     expect(document.querySelector('[data-reader-header-toolbar="true"]')).toBeTruthy();
     expect(await waitForSelector('[data-reader-rail-wrap="outline"]')).toBeTruthy();
+    const articleOutlineSlot = document.querySelector('[data-reader-outline-toolbar-slot]');
+    expect(articleOutlineSlot).toBeTruthy();
+    expect(articleOutlineSlot?.querySelector('[data-reader-rail-wrap="outline"]')).toBeTruthy();
     expect(shell?.querySelector('[data-reader-header-toolbar="true"]')).toBeNull();
 
     currentState.selectedConversation = {

tests/unit/article-reader-layout.test.ts

@@ -184,10 +184,13 @@ describe('ArticleReaderView layout', () => {
     expect(sentenceRoot?.style.maxWidth).toBe('var(--reader-content-width)');
   });
 
-  it('portals reader controls into the provided header target and keeps the inline rail for outline only', async () => {
+  it('portals reader controls and the outline rail into their provided header targets', async () => {
     const headerTarget = document.createElement('div');
     headerTarget.setAttribute('data-reader-header-toolbar-slot', 'true');
     document.body.appendChild(headerTarget);
+    const outlineTarget = document.createElement('div');
+    outlineTarget.setAttribute('data-reader-outline-toolbar-slot', 'true');
+    document.body.appendChild(outlineTarget);
     mocks.outlineEntries.push({
       index: 0,
       level: 1,
@@ -212,6 +215,8 @@ describe('ArticleReaderView layout', () => {
           setMessagesRootRef: vi.fn(),
           readerFeatures: { textLayout: true, theme: true, narration: true },
           readerToolbarPortalTarget: headerTarget,
+          readerOutlinePortalTarget: outlineTarget,
+          outlineScrollRoot: document.body,
         }),
       );
     });
@@ -221,9 +226,9 @@ describe('ArticleReaderView layout', () => {
     expect(headerTarget.querySelector('[data-testid="reader-header-toolbar"]')).toBeTruthy();
     const shell = document.querySelector('[data-reader-shell="article"]') as HTMLElement | null;
     expect(shell?.querySelector('[data-testid="reader-header-toolbar"]')).toBeNull();
-    const rail = shell?.querySelector('[data-reader-rail="article-rail"]') as HTMLElement | null;
+    expect(shell?.querySelector('[data-reader-rail="article-rail"]')).toBeNull();
+    const rail = outlineTarget.querySelector('[data-reader-rail="article-rail"]') as HTMLElement | null;
     expect(rail).toBeTruthy();
-    expect(rail?.className).toContain('tw-sticky');
-    expect(rail?.className).toContain('tw-top-5');
+    expect(rail?.querySelector('[data-testid="reader-toolbar"]')).toBeTruthy();
   });
 });