@plannotator/ui 0.54.0 → 0.56.0

package/contents-rail.css

@@ -0,0 +1,337 @@
+/*
+ * @plannotator/ui/contents-rail.css: the document contents rail
+ * (components/MarkdownContentsRail.tsx). Its own stylesheet, NOT part of
+ * theme.css or styles.css: import it OUTSIDE any CSS cascade layer, after the
+ * host's base reset. A layered copy loses to a later unlayered reset (the
+ * marker's margin-inline-start: auto, the tick, title and label paddings and
+ * margins, the depth indents), and the ticks then sit over the prose.
+ *
+ * Moved from the Workspaces app's `ws-markdown-contents-*` rules (approved
+ * 2026-10-03). A stable marker dock sits in the document's existing right
+ * padding without participating in layout. The Contents surface opens to its
+ * LEFT and may overlay the document, never a docked comments column. Pointer
+ * events stay on the real navigation buttons; selection and scrolling remain
+ * untouched. Plain CSS, no Tailwind. Tokens are the host's (Workspaces defines
+ * them all); each has a fallback.
+ */
+@keyframes pn-contents-rail-enter {
+  from {
+    opacity: 0;
+  }
+}
+
+.pn-contents-rail {
+  --pn-contents-dock-width: 36px;
+  --pn-contents-panel-gap: 6px;
+  --pn-contents-panel-width: 256px;
+
+  position: fixed;
+  z-index: 20;
+  translate: 0 -50%;
+  width: calc(
+    var(--pn-contents-dock-width) + var(--pn-contents-panel-gap) + var(--pn-contents-panel-width)
+  );
+  pointer-events: none;
+  animation: pn-contents-rail-enter var(--motion-duration-fast, 120ms)
+    var(--ease-enter, cubic-bezier(0.22, 1, 0.36, 1)) both;
+}
+
+.pn-contents-rail-dock {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: var(--pn-contents-dock-width);
+  pointer-events: none;
+}
+
+/* The floating surface (Workspaces' `floating-surface`: popover fill, no drawn
+ * border, the edge is the hairline ring in the menu shadow). */
+.pn-contents-rail-surface {
+  position: absolute;
+  top: -40px;
+  bottom: -8px;
+  left: 0;
+  width: var(--pn-contents-panel-width);
+  border-radius: var(--geometry-floating-radius, 10px);
+  background: var(--popover);
+  color: var(--popover-foreground);
+  box-shadow: var(
+    --shadow-menu,
+    0 0 0 1px color-mix(in oklch, var(--foreground) 8%, transparent),
+    0 12px 32px -8px color-mix(in oklch, var(--foreground) 22%, transparent)
+  );
+  transform: translateX(4px) scale(0.98);
+  transform-origin: right center;
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+/* The section eyebrow (Workspaces' EYEBROW: 12 px, weight 500). */
+.pn-contents-rail-title {
+  position: absolute;
+  top: -32px;
+  left: 8px;
+  display: flex;
+  width: calc(var(--pn-contents-panel-width) - 16px);
+  height: 28px;
+  align-items: center;
+  padding-inline: 4px;
+  color: var(--foreground);
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 20px;
+  transform: translateX(4px);
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+/* A host's one control at the right of the open panel's title (panelAction). */
+.pn-contents-rail-action {
+  position: absolute;
+  z-index: 2;
+  top: -32px;
+  right: calc(var(--pn-contents-dock-width) + var(--pn-contents-panel-gap) + 8px);
+  display: flex;
+  height: 28px;
+  align-items: center;
+  pointer-events: auto;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-surface,
+.pn-contents-rail[data-revealed] .pn-contents-rail-title {
+  transform: translateX(0) scale(1);
+  opacity: 1;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-title {
+  transition-delay: var(--motion-duration-basic, 150ms), var(--motion-duration-basic, 150ms);
+}
+
+.pn-contents-rail-list {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  /* The closed rail renders at most ten sampled document spans, so it never
+   * needs an internal scroll position. Shorter maps retain their natural
+   * height and stay centered by the rail's fixed midpoint anchor. */
+  max-height: 160px;
+  overflow-x: hidden;
+  overflow-y: hidden;
+  overscroll-behavior: contain;
+  scrollbar-width: none;
+  touch-action: none;
+  pointer-events: none;
+  transition: max-height var(--motion-duration-basic, 150ms) var(--ease-exit, cubic-bezier(0.4, 0, 0.2, 1));
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-list {
+  max-height: min(62vh, 560px);
+  overflow-y: auto;
+  transition-duration: var(--motion-duration-relaxed, 300ms);
+  transition-timing-function: var(--ease-enter, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+.pn-contents-rail-list::-webkit-scrollbar {
+  display: none;
+}
+
+.pn-contents-rail-marker {
+  --pn-contents-line-width: 26px;
+
+  position: relative;
+  display: flex;
+  width: var(--pn-contents-dock-width);
+  height: 16px;
+  flex-direction: row-reverse;
+  align-items: center;
+  justify-content: flex-start;
+  overflow: hidden;
+  margin-inline-start: auto;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  pointer-events: auto;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-marker {
+  width: 100%;
+  overflow: visible;
+}
+
+.pn-contents-rail-tick {
+  display: flex;
+  width: var(--pn-contents-dock-width);
+  flex: none;
+  align-items: center;
+  justify-content: flex-start;
+  padding-inline-start: 4px;
+}
+
+.pn-contents-rail-line {
+  --marker-progress: 0;
+
+  display: block;
+  width: var(--pn-contents-line-width);
+  height: 2px;
+  transform: scaleX(calc(0.6154 + 0.3846 * var(--marker-progress)));
+  transform-origin: left center;
+  background: var(--muted-foreground);
+  opacity: 0.4;
+  pointer-events: none;
+  transition: none;
+}
+
+/* The frequently scanned closed map updates immediately. The local lens is
+ * motion reserved for the explicitly opened Contents state. */
+.pn-contents-rail[data-revealed] .pn-contents-rail-line {
+  transition:
+    transform var(--motion-duration-basic, 150ms)
+      linear(0, 0.398 10%, 0.682 20%, 0.843 30%, 0.925 40%, 0.972 50%, 1.004 60%, 1.008 70%, 1.003 80%, 1),
+    opacity var(--motion-duration-basic, 150ms) ease,
+    background-color var(--motion-duration-basic, 150ms) ease;
+}
+
+/* H1:H2 is 12px:10px with the shorter line inset 2px toward the document, at
+ * a deliberately longer scale, then the same step for H3 and H4. */
+.pn-contents-rail-marker[data-level="2"] {
+  --pn-contents-line-width: 22px;
+}
+
+.pn-contents-rail-marker[data-level="3"] {
+  --pn-contents-line-width: 18px;
+}
+
+.pn-contents-rail-marker[data-level="4"] {
+  --pn-contents-line-width: 14px;
+}
+
+.pn-contents-rail-marker[data-current] .pn-contents-rail-line {
+  background: var(--primary);
+  opacity: 0.68;
+}
+
+.pn-contents-rail-marker[data-highlighted] .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible .pn-contents-rail-line {
+  --marker-progress: 1;
+  background: var(--foreground);
+  opacity: 1;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.7;
+  opacity: 0.78;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.4;
+  opacity: 0.58;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.2;
+  opacity: 0.46;
+}
+
+.pn-contents-rail-label {
+  display: block;
+  width: calc(var(--pn-contents-panel-width) - 16px);
+  height: 16px;
+  min-width: 0;
+  flex: none;
+  overflow: hidden;
+  margin-inline-end: calc(var(--pn-contents-panel-gap) + 8px);
+  padding-inline: 4px;
+  border-radius: var(--geometry-structure-radius, 4px);
+  background: transparent;
+  color: var(--muted-foreground);
+  font-size: inherit;
+  font-weight: 400;
+  line-height: 16px;
+  text-align: left;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  opacity: 0;
+  transform: translateX(-4px);
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    color var(--motion-duration-fast, 120ms) ease,
+    background-color var(--motion-duration-fast, 120ms) ease;
+}
+
+.pn-contents-rail-marker[data-depth="1"] .pn-contents-rail-label {
+  padding-inline-start: 16px;
+}
+
+.pn-contents-rail-marker[data-depth="2"] .pn-contents-rail-label {
+  padding-inline-start: 28px;
+}
+
+.pn-contents-rail-marker[data-depth="3"] .pn-contents-rail-label {
+  padding-inline-start: 40px;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-label {
+  opacity: 1;
+  transform: translateX(0);
+  transition-delay: var(--motion-duration-basic, 150ms), var(--motion-duration-basic, 150ms), 0ms, 0ms;
+}
+
+.pn-contents-rail-marker[data-current] .pn-contents-rail-label {
+  color: var(--foreground);
+}
+
+.pn-contents-rail-marker[data-highlighted] .pn-contents-rail-label,
+.pn-contents-rail-marker:focus-visible .pn-contents-rail-label {
+  background: var(--surface-hover, color-mix(in oklch, var(--foreground) 6%, transparent));
+  color: var(--foreground);
+}
+
+.pn-contents-rail:focus-within .pn-contents-rail-surface,
+.pn-contents-rail:focus-within .pn-contents-rail-title,
+.pn-contents-rail:focus-within .pn-contents-rail-label,
+.pn-contents-rail:focus-within .pn-contents-rail-list {
+  transition-duration: 0ms;
+  transition-delay: 0ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pn-contents-rail {
+    animation: none;
+  }
+  .pn-contents-rail-line {
+    transition: none;
+  }
+  .pn-contents-rail-surface,
+  .pn-contents-rail-title,
+  .pn-contents-rail-label,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-surface,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-title,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-label {
+    transform: none;
+    transition: opacity var(--motion-duration-fast, 120ms) ease;
+    transition-delay: 0ms;
+  }
+  .pn-contents-rail-list,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-list {
+    transition: none;
+  }
+}

package/hooks/useActiveSection.ts

@@ -1,81 +1,64 @@
-import { useEffect, useState, useRef } from 'react';
-import { getScrollViewportIntersectionRoot } from './useScrollViewport';
+import { useEffect, useState } from 'react';
+import { CONTENTS_ACTIVATION_OFFSET } from '../utils/headingScrollSpy';
+import { addScrollViewportListener, getScrollViewportRect } from './useScrollViewport';
 
-/**
- * Track which heading section is currently visible in the viewport
- * Uses Intersection Observer to detect when headings enter/leave view
- */
+/** Track the heading at the reading line, even when a scroll skips whole sections. */
 export function useActiveSection(
   containerRef: React.RefObject<HTMLElement | null>,
   headingCount: number,
-  /** Optional explicit scroll element. When provided, takes precedence over
-   *  containerRef.current and re-runs the effect when it changes — needed
-   *  for OverlayScrollArea, whose viewport is only available after mount. */
+  /** Optional explicit scroll element, available after OverlayScrollArea mounts. */
   scrollElement?: HTMLElement | null,
 ) {
   const [activeId, setActiveId] = useState<string | null>(null);
-  const observerRef = useRef<IntersectionObserver | null>(null);
 
   useEffect(() => {
     const contentContainer = containerRef.current ?? scrollElement;
     const viewport = scrollElement ?? contentContainer;
     if (!contentContainer || !viewport) return;
-    
-    // Only document headings: a heading inside a question card's context has
-    // no block id and is not a TOC section.
-    const headings = contentContainer.querySelectorAll('[data-block-type="heading"][data-block-id]');
-    if (headings.length === 0) return;
-    
-    // Track which headings are currently intersecting
-    const intersectingHeadings = new Map<Element, boolean>();
-    
-    // Create observer with configuration to detect headings near top of viewport
-    observerRef.current = new IntersectionObserver(
-      (entries) => {
-        // Update intersection state
-        entries.forEach(entry => {
-          intersectingHeadings.set(entry.target, entry.isIntersecting);
-        });
-        
-        // Find the first intersecting heading (topmost in viewport)
-        let topHeading: Element | null = null;
-        let topPosition = Infinity;
-        
-        for (const [heading, isIntersecting] of intersectingHeadings) {
-          if (isIntersecting) {
-            const rect = heading.getBoundingClientRect();
-            if (rect.top < topPosition) {
-              topPosition = rect.top;
-              topHeading = heading;
-            }
-          }
-        }
-        
-        // Update active ID
-        if (topHeading) {
-          const blockId = topHeading.getAttribute('data-block-id');
-          if (blockId) {
-            setActiveId(blockId);
-          }
-        }
-      },
-      {
-        root: getScrollViewportIntersectionRoot(viewport),
-        rootMargin: '-80px 0px -80% 0px', // Activate when heading is near top
-        threshold: [0, 0.1, 0.5, 1.0],
+
+    const refresh = () => {
+      // Read current nodes, not a count-keyed snapshot: another document can
+      // replace every heading while keeping the same count and block ids.
+      const headings = contentContainer.querySelectorAll<HTMLElement>(
+        '[data-block-type="heading"][data-block-id]',
+      );
+      const readingLine = getScrollViewportRect(viewport).top + CONTENTS_ACTIVATION_OFFSET;
+      let current: HTMLElement | null = null;
+      for (const heading of headings) {
+        if (heading.getClientRects().length === 0) continue;
+        current ??= heading;
+        if (heading.getBoundingClientRect().top <= readingLine) current = heading;
+        else break;
       }
-    );
-    
-    // Observe all headings
-    headings.forEach(heading => {
-      observerRef.current?.observe(heading);
-    });
-    
-    // Cleanup
+      setActiveId(current?.dataset.blockId ?? null);
+    };
+
+    let frame: number | null = null;
+    const scheduleRefresh = () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        refresh();
+      });
+    };
+    refresh();
+    const removeScrollListener = addScrollViewportListener(viewport, scheduleRefresh);
+    window.addEventListener('resize', scheduleRefresh);
+    const resizeObserver = typeof ResizeObserver === 'undefined'
+      ? null : new ResizeObserver(scheduleRefresh);
+    resizeObserver?.observe(contentContainer);
+    if (viewport !== contentContainer) resizeObserver?.observe(viewport);
+    const mutationObserver = new MutationObserver(scheduleRefresh);
+    mutationObserver.observe(contentContainer, { childList: true, characterData: true, subtree: true });
+
     return () => {
-      observerRef.current?.disconnect();
+      if (frame !== null) cancelAnimationFrame(frame);
+      removeScrollListener();
+      window.removeEventListener('resize', scheduleRefresh);
+      resizeObserver?.disconnect();
+      mutationObserver.disconnect();
     };
   }, [containerRef, headingCount, scrollElement]);
-  
+
   return activeId;
 }

package/hooks/useAnnotationHighlighter.ts

@@ -421,6 +421,17 @@ const excludedAncestor = (node: Node | null): HTMLElement | null => {
   return element?.closest<HTMLElement>(ANNOTATION_EXCLUDED_SELECTOR) ?? null;
 };
 
+/**
+ * The whole range sits inside one `.annotation-exclude` subtree of `container`
+ * (an Inbox action item or question card under text comments, a diagram):
+ * nothing in it can be annotated, so the selection is left to the person.
+ * An excluded element around the container itself does not count.
+ */
+export const rangeInsideExcluded = (container: HTMLElement, range: Range): boolean => {
+  const excluded = excludedAncestor(range.commonAncestorContainer);
+  return excluded !== null && excluded !== container && container.contains(excluded);
+};
+
 /**
  * Move a range's start off any `.annotation-exclude` subtree it begins inside,
  * onto the first annotatable text position the range covers.
@@ -1508,6 +1519,9 @@ export function useAnnotationHighlighter({
       trimWhitespaceOnlyBoundaryNodes(args[1] as SelectedNodeLike[])) as SelectedNodesTap);
 
     highlighterRef.current = highlighter;
+    // Whether the library's pointer-end handler is attached (`run()`), and whether this effect was cleaned up.
+    let listening = false;
+    let disposed = false;
 
     // Stored positions can resolve into chrome the reviewer could never have
     // selected; painting never enters such a subtree, so a boundary left there
@@ -1650,6 +1664,25 @@ export function useAnnotationHighlighter({
       // AROUND the document and whose end boundary is an empty <div> — the
       // exact shape that throws — so a containment bail here would hand that
       // selection straight to the serializer.
+      if (rangeInsideExcluded(container, range)) {
+        // Nothing here can be annotated (an Inbox action item or question
+        // card under text comments, a diagram): the selection is the
+        // person's to copy. The library's own pointer-end handler paints
+        // nothing for it and then removes the DOM selection anyway, so it
+        // sits this one event out (a listener removed during dispatch never
+        // runs) and listens again on the next task.
+        pendingRangeRunsRef.current = null;
+        if (listening) {
+          highlighter.stop();
+          listening = false;
+          window.setTimeout(() => {
+            if (disposed) return;
+            highlighter.run();
+            listening = true;
+          }, 0);
+        }
+        return;
+      }
       if (isBlankQuote(selection.toString()) || !isSerializableRange(range)) {
         pendingRangeRunsRef.current = null;
         selection.removeAllRanges();
@@ -1676,7 +1709,10 @@ export function useAnnotationHighlighter({
     // person chooses its Comment (takeSelection); the library painting it at
     // touchend would end the system selection and its edit menu first.
     const isTouchPrimary = window.matchMedia('(pointer: coarse)').matches;
-    if (!(isTouchPrimary && hostComposesRef.current)) highlighter.run();
+    if (!(isTouchPrimary && hostComposesRef.current)) {
+      highlighter.run();
+      listening = true;
+    }
 
     const handleMathMouseDown = (event: MouseEvent) => {
       mouseDownMathRef.current = closestMathElement(event.target as Node, containerRef.current);
@@ -1773,6 +1809,8 @@ export function useAnnotationHighlighter({
       if (!sel || sel.isCollapsed || sel.rangeCount === 0) return false;
       if (!containerRef.current?.contains(sel.anchorNode)) return false;
       const range = sel.getRangeAt(0).cloneRange();
+      // Nothing to annotate there: the system selection and its copy menu stay the person's.
+      if (rangeInsideExcluded(containerRef.current, range)) return false;
       // Same fail-closed rule as the pointer-end guard (#881): touch
       // selections settle on block boundaries just as often.
       if (isBlankQuote(sel.toString()) || !isSerializableRange(range)) return false;
@@ -1810,6 +1848,7 @@ export function useAnnotationHighlighter({
       containerRef.current?.removeEventListener('mouseup', handleMathMouseUp, true);
       container.removeEventListener('mouseup', handlePointerEndCapture, true);
       container.removeEventListener('touchend', handlePointerEndCapture, true);
+      disposed = true;
       highlighter.dispose();
     };
   }, [clearPendingSelection, enabled]);

package/hooks/useFileBrowser.ts

@@ -9,6 +9,7 @@
 
 import { useState, useCallback, useEffect, useMemo, useRef } from "react";
 import type { VaultNode } from "../types";
+import { basenameFromPath } from "@plannotator/core/source-save";
 import type { WorkspaceStatusPayload } from "@plannotator/core/workspace-status-types";
 
 export interface DirState {
@@ -200,7 +201,7 @@ export function useFileBrowser(): UseFileBrowserReturn {
   }, []);
 
   const fetchTree = useCallback(async (dirPath: string, options: { quiet?: boolean } = {}) => {
-    const name = dirPath.split("/").pop() || dirPath;
+    const name = basenameFromPath(dirPath);
 
     setDirs((prev) => {
       const exists = prev.find((d) => d.path === dirPath);
@@ -291,7 +292,7 @@ export function useFileBrowser(): UseFileBrowserReturn {
         const vaultDirs = prev.filter((d) => d.isVault);
         const regularDirs = directories.map((path) => ({
           path,
-          name: path.split("/").pop() || path,
+          name: basenameFromPath(path),
           tree: [],
           // Keep initial roots loading until their first snapshot resolves. If
           // the SSE watcher starts before /api/reference/files finishes,
@@ -313,7 +314,7 @@ export function useFileBrowser(): UseFileBrowserReturn {
   }, []);
 
   const addVaultDir = useCallback(async (vaultPath: string) => {
-    const name = vaultPath.split("/").pop() || vaultPath;
+    const name = basenameFromPath(vaultPath);
 
     // Atomically replace any existing vault dirs (handles vault path change without accumulating stale entries)
     setDirs((prev) => {

package/hooks/useHeadingScrollSpy.ts

@@ -0,0 +1,77 @@
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { activeHeadingBinding, bindHeadings, type HeadingBinding } from '../utils/headingScrollSpy';
+
+/**
+ * The block id of the heading being read in `scrollViewport`, by the contents
+ * rail's own scroll math (utils/headingScrollSpy): cached heading tops, read
+ * on every scroll frame, the last heading at the document's end. For a
+ * Contents list on the rail's surface (`DocumentContents`), so the two never
+ * disagree. Plan review's list keeps `useActiveSection`.
+ *
+ * Reads at once on mount (a sheet opened mid-document marks the section being
+ * read on its first paint), and re-binds when the document's elements change
+ * (an edit can replace the headings and keep their count) or resize. Before
+ * any heading is drawn the answer stays what it was.
+ */
+export function useHeadingScrollSpy(
+  scrollViewport: HTMLElement | null,
+  blockIds: readonly string[],
+): string | null {
+  const idsKey = blockIds.join('\n');
+  // Stable while the ids are the same, whatever array the caller passes.
+  const ids = useMemo(() => (idsKey === '' ? [] : idsKey.split('\n')), [idsKey]);
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const bindingsRef = useRef<readonly HeadingBinding[]>([]);
+
+  const refresh = useCallback(() => {
+    if (scrollViewport === null) return;
+    const binding = activeHeadingBinding(bindingsRef.current, scrollViewport);
+    if (binding !== null) setActiveIndex(binding.itemIndex);
+  }, [scrollViewport]);
+
+  useLayoutEffect(() => {
+    setActiveIndex(null);
+    bindingsRef.current = [];
+    if (scrollViewport === null || ids.length === 0) return;
+    const rebind = () => {
+      bindingsRef.current = bindHeadings(scrollViewport, ids);
+      refresh();
+    };
+    rebind();
+
+    let scrollFrame: number | null = null;
+    const onScroll = () => {
+      if (scrollFrame !== null) return;
+      scrollFrame = requestAnimationFrame(() => {
+        scrollFrame = null;
+        refresh();
+      });
+    };
+    let bindFrame: number | null = null;
+    const scheduleRebind = () => {
+      if (bindFrame !== null) cancelAnimationFrame(bindFrame);
+      bindFrame = requestAnimationFrame(() => {
+        bindFrame = null;
+        rebind();
+      });
+    };
+    scrollViewport.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', scheduleRebind);
+    const resizeObserver =
+      typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(scheduleRebind);
+    resizeObserver?.observe(scrollViewport);
+    const mutationObserver =
+      typeof MutationObserver === 'undefined' ? null : new MutationObserver(scheduleRebind);
+    mutationObserver?.observe(scrollViewport, { childList: true, subtree: true });
+    return () => {
+      if (scrollFrame !== null) cancelAnimationFrame(scrollFrame);
+      if (bindFrame !== null) cancelAnimationFrame(bindFrame);
+      scrollViewport.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', scheduleRebind);
+      resizeObserver?.disconnect();
+      mutationObserver?.disconnect();
+    };
+  }, [ids, refresh, scrollViewport]);
+
+  return activeIndex === null ? null : (ids[activeIndex] ?? null);
+}