@plannotator/ui 0.54.0 → 0.56.0

package/components/CodeSnippetPreview.tsx

@@ -0,0 +1,174 @@
+import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { ensureHighlight, highlightToHtml } from "../utils/codeHighlight";
+import { useFenceTheme } from "../hooks/useFenceTheme";
+
+/**
+ * The floating code window a code-file reference opens on hover: a few lines
+ * of one file, syntax highlighted, with line numbers. Portalled to the body
+ * and positioned under (or above) its anchor.
+ *
+ * Used by plan / annotate code-file links (`CodeFileLink` in InlineMarkdown,
+ * the exact range only) and by code review's Call Flow locations
+ * (`CallFlowTreeView`, with `contextLines` around the target).
+ */
+
+/** Lines highlighted above the shown ones so a range opening inside a block comment or string tokenises as one. */
+const HIGHLIGHT_LEAD_IN_LINES = 40;
+/** Gap kept between the window and the viewport edge. */
+const VIEWPORT_MARGIN = 8;
+
+/** The highlighter language for a file path, by extension; undefined renders plain text. */
+export function codeSnippetLanguage(filepath: string): string | undefined {
+  const ext = filepath.split('.').pop()?.toLowerCase();
+  const map: Record<string, string> = {
+    ts: 'typescript', tsx: 'typescript', js: 'javascript', jsx: 'javascript',
+    mts: 'typescript', cts: 'typescript', mjs: 'javascript', cjs: 'javascript',
+    py: 'python', rb: 'ruby', rs: 'rust', go: 'go', java: 'java',
+    css: 'css', scss: 'scss', json: 'json', yml: 'yaml', yaml: 'yaml',
+    sql: 'sql', sh: 'bash', bash: 'bash', zsh: 'bash', md: 'markdown',
+    html: 'html', xml: 'xml', toml: 'toml', swift: 'swift', kt: 'kotlin',
+    lua: 'lua', c: 'c', h: 'c', cpp: 'cpp', hpp: 'cpp', cs: 'csharp',
+    scala: 'scala', dart: 'dart', ex: 'elixir', exs: 'elixir', zig: 'zig',
+    vue: 'vue', svelte: 'svelte', astro: 'astro', php: 'php',
+  };
+  return ext ? map[ext] : undefined;
+}
+
+export interface CodeSnippetPreviewProps {
+  anchorEl: HTMLElement | null;
+  /** The whole file; the preview slices the lines it shows. */
+  contents: string;
+  filepath: string;
+  /** One-based first line of the target range. */
+  line: number;
+  lineEnd?: number;
+  /** Lines shown above and below the target range, the target rows marked. 0 (default) shows the range alone. */
+  contextLines?: number;
+  /** Header label; defaults to the file's basename. */
+  title?: string;
+  /** Called when the page or a scroller scrolls: the window is placed once and would drift from its anchor. */
+  onDismiss?: () => void;
+  onMouseEnter?: () => void;
+  onMouseLeave?: () => void;
+}
+
+export const CodeSnippetPreview: React.FC<CodeSnippetPreviewProps> = ({
+  anchorEl,
+  contents,
+  filepath,
+  line,
+  lineEnd,
+  contextLines = 0,
+  title,
+  onDismiss,
+  onMouseEnter,
+  onMouseLeave,
+}) => {
+  const allLines = contents.split('\n');
+  const targetStart = Math.max(0, line - 1);
+  const targetEnd = Math.min(allLines.length, lineEnd ?? line);
+  const start = Math.max(0, targetStart - contextLines);
+  const end = Math.min(allLines.length, targetEnd + contextLines);
+  const snippet = allLines.slice(start, end).join('\n');
+  // Highlight from a little earlier than the first shown line: a range that
+  // starts inside a block comment or template literal would otherwise colour
+  // that text as code.
+  const highlightStart = Math.max(0, start - HIGHLIGHT_LEAD_IN_LINES);
+  const highlightSource = allLines.slice(highlightStart, end).join('\n');
+  const marksTarget = contextLines > 0;
+
+  const fenceTheme = useFenceTheme();
+  // Bumped once the grammar is attached, to re-run the memo below with the
+  // highlighter warm. Until then the snippet renders as plain text — no
+  // auto-detection, and an unknown extension simply stays plain.
+  const [highlighterGeneration, setHighlighterGeneration] = useState(0);
+  const lang = codeSnippetLanguage(filepath);
+
+  useEffect(() => {
+    if (!lang) return;
+    let cancelled = false;
+    void ensureHighlight(lang, fenceTheme).then((ok) => {
+      if (ok && !cancelled) setHighlighterGeneration((n) => n + 1);
+    });
+    return () => { cancelled = true; };
+  }, [lang, fenceTheme]);
+
+  useEffect(() => {
+    if (!onDismiss) return;
+    const dismiss = () => onDismiss();
+    window.addEventListener('scroll', dismiss, { capture: true, passive: true });
+    return () => window.removeEventListener('scroll', dismiss, { capture: true });
+  }, [onDismiss]);
+
+  const highlightedLines = useMemo(() => {
+    // Highlight the snippet as one unit so multi-line constructs (block
+    // comments, template literals) tokenise correctly, then split back into
+    // rows: the highlighter joins lines with "\n" and never emits one inside a
+    // span, so the split is exact.
+    const html = lang ? highlightToHtml(highlightSource, lang, fenceTheme) : null;
+    if (html !== null) return html.split('\n').slice(start - highlightStart);
+    return snippet.split('\n').map(text =>
+      text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'));
+    // highlighterGeneration is the "grammar just became available" signal.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [snippet, highlightSource, start, highlightStart, lang, fenceTheme, highlighterGeneration]);
+
+  // Clamp against the window's rendered width (it sizes to its longest line,
+  // up to its max width) so a wide snippet never runs off the right edge.
+  const windowRef = useRef<HTMLDivElement | null>(null);
+  const [renderedWidth, setRenderedWidth] = useState<number | null>(null);
+  useLayoutEffect(() => {
+    const width = windowRef.current?.offsetWidth ?? null;
+    if (width !== renderedWidth) setRenderedWidth(width);
+  });
+
+  if (!anchorEl) return null;
+
+  const rect = anchorEl.getBoundingClientRect();
+  const spaceBelow = window.innerHeight - rect.bottom;
+  const showAbove = spaceBelow < 200 && rect.top > spaceBelow;
+  const top = showAbove ? undefined : rect.bottom + 4;
+  const bottom = showAbove ? window.innerHeight - rect.top + 4 : undefined;
+  const left = Math.max(VIEWPORT_MARGIN, Math.min(rect.left, window.innerWidth - (renderedWidth ?? 520) - VIEWPORT_MARGIN));
+
+  return createPortal(
+    <div
+      ref={windowRef}
+      className="code-snippet-preview-window fixed z-[9999] rounded-lg border border-border bg-card shadow-xl flex flex-col"
+      style={{ top, bottom, left, maxWidth: `min(600px, calc(100vw - ${VIEWPORT_MARGIN * 2}px))`, maxHeight: '300px' }}
+      data-code-snippet-preview={filepath}
+      onMouseEnter={onMouseEnter}
+      onMouseLeave={onMouseLeave}
+    >
+      <div className="px-3 py-1.5 border-b border-border/50 text-[10px] text-muted-foreground font-mono flex items-center justify-between gap-4 flex-shrink-0">
+        <span>{title ?? filepath.split('/').pop()}</span>
+        <span className="opacity-60">{lineEnd && lineEnd !== line ? `lines ${line}–${lineEnd}` : `line ${line}`}</span>
+      </div>
+      <div className="code-snippet-preview overflow-auto text-[12px] leading-5 min-h-0" style={{ padding: 0, background: 'var(--code-bg, #1e293b)' }}>
+        <table className="border-collapse w-full">
+          <tbody>
+            {snippet.split('\n').map((_, i) => {
+              const index = start + i;
+              const target = marksTarget && index >= targetStart && index < targetEnd;
+              return (
+                <tr
+                  key={index}
+                  className={target ? 'bg-primary/15' : 'hover:bg-white/5'}
+                  data-target-line={target ? 'true' : undefined}
+                >
+                  <td className={`select-none text-right pr-3 pl-3 py-0 align-top font-mono w-8 whitespace-nowrap ${target ? 'text-primary' : 'text-muted-foreground/40'}`} style={{ userSelect: 'none' }}>{index + 1}</td>
+                  <td
+                    className="font-mono pr-3 py-0 whitespace-pre"
+                    dangerouslySetInnerHTML={{ __html: highlightedLines[i] ?? '' }}
+                  />
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+    </div>,
+    document.body,
+  );
+};

package/components/ComposerTokenTextarea.tsx

@@ -207,6 +207,16 @@ export interface ComposerTokenTextareaProps {
     React.TextareaHTMLAttributes<HTMLTextAreaElement>,
     'value' | 'onChange' | 'onKeyDown' | 'onSelect' | 'onScroll' | 'className' | 'placeholder'
   >;
+  /** Paint on the mirror that is not in the value. Same metric rule as the token spans: it must add no width. */
+  mirrorPaint?: ComposerMirrorPaint;
+}
+
+export interface ComposerMirrorPaint {
+  /** Drawn at this offset (past the end of a token it falls inside). */
+  at?: number;
+  node?: React.ReactNode;
+  /** A range of plain text behind a mark. A token inside it keeps its own paint. */
+  wash?: { start: number; end: number; className: string };
 }
 
 /**
@@ -241,6 +251,7 @@ export const ComposerTokenTextarea: React.FC<ComposerTokenTextareaProps> = ({
   inputClassName,
   mirrorClassName,
   inputProps,
+  mirrorPaint,
 }) => {
   const overlayRef = useRef<HTMLDivElement>(null);
   const [composing, setComposing] = useState(false);
@@ -325,15 +336,45 @@ export const ComposerTokenTextarea: React.FC<ComposerTokenTextareaProps> = ({
   }
 
   const segments: React.ReactNode[] = [];
+  let paintDrawn = false;
+  /** One run of plain text, cut at the paint's offsets. With no paint, the plain string as ever. */
+  const pushPlain = (start: number, end: number) => {
+    if (!mirrorPaint) {
+      segments.push(value.slice(start, end));
+      return;
+    }
+    const { at, node, wash } = mirrorPaint;
+    const cuts = [start, end, ...[at, wash?.start, wash?.end].filter((cut): cut is number => cut !== undefined && cut > start && cut < end)].sort((a, b) => a - b);
+    for (let i = 0; i + 1 < cuts.length; i++) {
+      const from = cuts[i]!;
+      const to = cuts[i + 1]!;
+      if (!paintDrawn && at !== undefined && from >= at) {
+        paintDrawn = true;
+        segments.push(<React.Fragment key="mirror-paint">{node}</React.Fragment>);
+      }
+      if (from === to) continue;
+      const text = value.slice(from, to);
+      segments.push(
+        wash && from >= wash.start && to <= wash.end ? (
+          <mark key={`mirror-wash-${from}`} className={wash.className}>
+            {text}
+          </mark>
+        ) : (
+          text
+        ),
+      );
+    }
+  };
   let pos = 0;
   for (const range of ranges) {
-    if (range.start > pos) segments.push(value.slice(pos, range.start));
+    if (range.start > pos) pushPlain(pos, range.start);
     segments.push(
       renderTokenSpan(range, value.slice(range.start, range.end), mentionChips?.tokenClassName),
     );
     pos = range.end;
   }
-  segments.push(value.slice(pos));
+  pushPlain(pos, value.length);
+  if (mirrorPaint?.at !== undefined && !paintDrawn) segments.push(<React.Fragment key="mirror-paint">{mirrorPaint.node}</React.Fragment>);
 
   return (
     <div className="relative">

package/components/DeferredMarkdownContentsRail.tsx

@@ -0,0 +1,38 @@
+// Moved from the Workspaces app's DeferredMarkdownContentsRail with its
+// contents rail (MarkdownContentsRail, approved 2026-10-03). Port: the props
+// are the rail's own (`MarkdownContentsRailProps`), passed through.
+
+import { lazy, Suspense, useEffect, useState } from 'react';
+
+import type { MarkdownContentsRailProps } from './MarkdownContentsRail';
+
+const MarkdownContentsRail = lazy(() =>
+  import('./MarkdownContentsRail').then((module) => ({
+    default: module.MarkdownContentsRail,
+  })),
+);
+
+export function scheduleMarkdownContentsRail(callback: () => void): () => void {
+  if (typeof window.requestIdleCallback === 'function') {
+    const handle = window.requestIdleCallback(callback, { timeout: 2000 });
+    return () => window.cancelIdleCallback(handle);
+  }
+  const handle = window.setTimeout(callback, 0);
+  return () => window.clearTimeout(handle);
+}
+
+/** Load the reading aid after the document is interactive, never in the
+ * critical document-paint path. The timeout still guarantees it appears on
+ * a busy page; Safari and tests use the zero-delay fallback. */
+export function DeferredMarkdownContentsRail(props: MarkdownContentsRailProps) {
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => scheduleMarkdownContentsRail(() => setReady(true)), []);
+
+  if (!ready) return null;
+  return (
+    <Suspense fallback={null}>
+      <MarkdownContentsRail {...props} />
+    </Suspense>
+  );
+}

package/components/DiffFileTree.tsx

@@ -11,12 +11,13 @@ export type { DiffFileTreeFile, DiffFileTreeNode, DiffFileTreeStatus } from '../
 export type { DiffFileTreeDefaultExpanded } from '../hooks/useDiffFileTreeExpansion';
 
 /*
- * The diff file tree's presentational parts. Plannotator's code review renders
- * its tree rows from the atoms below (folder row, file-row content, change
- * letter, +/- counts, indentation), adding its review-only decorations
- * (viewed/stage controls, annotation badge, context menu) around them; the
- * `DiffFileTree` component at the bottom is the read-only, embeddable tree a
- * host drops beside its own diff list.
+ * The diff file tree's presentational parts: the atoms below (folder row,
+ * file-row content, change letter, +/- counts, indentation) for a host's own
+ * rows, and the `DiffFileTree` component at the bottom, the read-only,
+ * embeddable tree a host drops beside its own diff list. Plannotator's code
+ * review shares `ChangeTypeLetter` and `diffFileTreeIndent` (its All files
+ * tree) but draws its own Changes rows since its aligned sidebar (see
+ * HANDOFF.md § "Diff file tree").
  */
 
 /** Left padding of a row at `depth` (px). */

package/components/DocBadges.tsx

@@ -19,7 +19,9 @@ import React from 'react';
 import { PlanDiffBadge } from './plan-diff/PlanDiffBadge';
 import type { PlanDiffStats } from '../utils/planDiffEngine';
 import { hostnameOrFallback } from '@plannotator/core/project';
+import { basenameFromPath } from '@plannotator/core/source-save';
 import { OpenInAppButton } from './OpenInAppButton';
+import { HostTitle } from './HostTitle';
 
 export interface LinkedDocBadgeInfo {
   filepath: string;
@@ -74,8 +76,11 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
   const isHorizontal = layout !== 'column';
   const canOpenInApp =
     !!openInAppPath && !/^https?:\/\//i.test(openInAppPath);
+  // Never shrinks: a file name chip beside it gives up its width first.
   const openInButton = canOpenInApp ? (
-    <OpenInAppButton filePath={openInAppPath} base={null} />
+    <span className="flex flex-shrink-0">
+      <OpenInAppButton filePath={openInAppPath} base={null} />
+    </span>
   ) : null;
 
   // In row layout, only PlanDiffBadge (when it has stats to show) and
@@ -100,24 +105,32 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
           under the action buttons. The Viewer-owned header measures and wraps
           the complete badge set, so its `header` layout keeps this context. */}
       {repoInfo && !linkedDocInfo && !isRow && (
-        <div className="flex items-center gap-1.5">
-          <span
-            className="px-1.5 py-0.5 bg-muted/50 rounded truncate max-w-[140px]"
-            title={repoInfo.display}
-          >
-            {repoInfo.display}
-          </span>
-          {repoInfo.branch && (
-            <span
-              className="px-1.5 py-0.5 bg-muted/30 rounded max-w-[120px] flex items-center gap-1 overflow-hidden"
-              title={repoInfo.branch}
-            >
-              <svg className="w-2.5 h-2.5 flex-shrink-0" viewBox="0 0 16 16" fill="currentColor">
-                <path d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z" />
-              </svg>
-              <span className="truncate">{repoInfo.branch}</span>
-            </span>
-          )}
+        <div className="flex min-w-0 max-w-full items-center gap-1.5">
+          {/* No fixed caps: the chips take the room the cluster has. When it runs
+              out, the branch gives way first, down to its icon and a letter or
+              two, and only then the repository: the repository never shrinks,
+              but stops short of the branch's floor (4.5em) and the gap. */}
+          <div className="flex min-w-0 items-center gap-1.5">
+            <HostTitle title={repoInfo.display} cut>
+              <span
+                className={`truncate px-1.5 py-0.5 bg-muted/50 rounded ${
+                  repoInfo.branch ? 'flex-shrink-0 max-w-[calc(100%_-_4.5em_-_0.375rem)]' : 'min-w-0'
+                }`}
+              >
+                {repoInfo.display}
+              </span>
+            </HostTitle>
+            {repoInfo.branch && (
+              <HostTitle title={repoInfo.branch} cut>
+                <span className="min-w-[4.5em] px-1.5 py-0.5 bg-muted/30 rounded flex items-center gap-1 overflow-hidden">
+                  <svg className="w-2.5 h-2.5 flex-shrink-0" viewBox="0 0 16 16" fill="currentColor">
+                    <path d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z" />
+                  </svg>
+                  <span className="truncate">{repoInfo.branch}</span>
+                </span>
+              </HostTitle>
+            )}
+          </div>
           {/* Markdown/text annotate sessions have no separate source badge, so
               keep the open-in control attached to the repository context. */}
           {canOpenInApp && !sourceInfo && openInButton}
@@ -199,7 +212,7 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
       {/* Linked-doc breadcrumb: only in column layout (sticky lane is hidden in linked-doc mode) */}
       {!isRow && linkedDocInfo && (
         linkedDocInfo.variant === 'folder-file' ? (
-          <div className="flex items-center gap-2">
+          <div className="flex min-w-0 max-w-full items-center gap-2">
             {linkedDocInfo.onBack && (
               <button
                 type="button"
@@ -209,19 +222,19 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
                 Close
               </button>
             )}
-            <span
-              className="truncate rounded bg-muted/50 px-1.5 py-0.5 text-[9px] text-muted-foreground max-w-[220px]"
-              title={linkedDocInfo.filepath}
-            >
-              {linkedDocInfo.filepath.split('/').pop()}
-            </span>
+            {/* The hover text is the whole path, so it shows whether or not the name is cut. */}
+            <HostTitle title={linkedDocInfo.filepath}>
+              <span className="min-w-0 truncate rounded bg-muted/50 px-1.5 py-0.5 text-[9px] text-muted-foreground">
+                {basenameFromPath(linkedDocInfo.filepath)}
+              </span>
+            </HostTitle>
             {openInButton}
           </div>
         ) : (
-          <div className="flex items-center gap-1.5">
+          <div className="flex min-w-0 max-w-full items-center gap-1.5">
             <button
               onClick={linkedDocInfo.onBack}
-              className="px-1.5 py-0.5 bg-primary/10 text-primary rounded hover:bg-primary/20 transition-colors flex items-center gap-1"
+              className="px-1.5 py-0.5 bg-primary/10 text-primary rounded hover:bg-primary/20 transition-colors flex flex-shrink-0 items-center gap-1"
             >
               <svg
                 className="w-2.5 h-2.5"
@@ -238,15 +251,14 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
               </svg>
               {linkedDocInfo.backLabel || 'plan'}
             </button>
-            <span className="px-1.5 py-0.5 bg-primary/10 text-primary/80 rounded">
+            <span className="px-1.5 py-0.5 bg-primary/10 text-primary/80 rounded flex-shrink-0">
               {linkedDocInfo.label || 'Linked File'}
             </span>
-            <span
-              className="px-1.5 py-0.5 bg-muted/50 text-muted-foreground rounded truncate max-w-[200px]"
-              title={linkedDocInfo.filepath}
-            >
-              {linkedDocInfo.filepath.split('/').pop()}
-            </span>
+            <HostTitle title={linkedDocInfo.filepath}>
+              <span className="min-w-0 px-1.5 py-0.5 bg-muted/50 text-muted-foreground rounded truncate">
+                {basenameFromPath(linkedDocInfo.filepath)}
+              </span>
+            </HostTitle>
             {openInButton}
           </div>
         )

package/components/DocumentContents.tsx

@@ -0,0 +1,74 @@
+import { useLayoutEffect, useMemo, useRef } from 'react';
+import type { Annotation, Block } from '../types';
+import { CONTENTS_RAIL_MAX_LEVEL, tocHeadings } from '../utils/annotationHelpers';
+import { useHeadingScrollSpy } from '../hooks/useHeadingScrollSpy';
+import { TableOfContents } from './TableOfContents';
+
+interface DocumentContentsProps {
+  blocks: Block[];
+  annotations: Annotation[];
+  /**
+   * The element the document scrolls in. The current heading is read from it
+   * and a click scrolls it. `null` until it has mounted.
+   */
+  scrollViewport: HTMLElement | null;
+  /** Called with the heading's block id after a click (a sheet closes itself here). */
+  onNavigate?: (blockId: string) => void;
+  className?: string;
+}
+
+/**
+ * A document's Contents list for a host without plan review's sidebar, on the
+ * contents rail's surface (the Inbox's sheet, where the rail yields): the same
+ * `TableOfContents` (click to scroll, the current heading highlighted) with
+ * the rail's headings (levels 1 to 4) and the rail's scroll math
+ * (`useHeadingScrollSpy`), so the list and the rail never disagree. It draws
+ * no chrome; the host places it and titles it.
+ *
+ * The host mounts it afresh (a sheet that opens), often mid-document: the
+ * current heading is read at once. The marked entry is kept in view inside the
+ * list's own scroll box (a sheet).
+ */
+export function DocumentContents({ blocks, annotations, scrollViewport, onNavigate, className = '' }: DocumentContentsProps) {
+  const headingIds = useMemo(
+    () => tocHeadings(blocks, CONTENTS_RAIL_MAX_LEVEL).map((heading) => heading.id),
+    [blocks],
+  );
+  const activeId = useHeadingScrollSpy(scrollViewport, headingIds);
+
+  const wrapRef = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    const item = wrapRef.current?.querySelector<HTMLElement>('[aria-current="location"]');
+    if (item) revealInList(item);
+  }, [activeId]);
+
+  return (
+    <div ref={wrapRef} style={{ display: 'contents' }}>
+      <TableOfContents
+        blocks={blocks}
+        annotations={annotations}
+        activeId={activeId}
+        onNavigate={onNavigate ?? noop}
+        scrollViewport={scrollViewport}
+        maxLevel={CONTENTS_RAIL_MAX_LEVEL}
+        className={className}
+      />
+    </div>
+  );
+}
+
+/**
+ * Scroll the list's own scroll box (the nearest ancestor that scrolls) just
+ * enough to show `item`, at once. Never the page or the document behind it.
+ */
+function revealInList(item: HTMLElement) {
+  let box = item.parentElement;
+  while (box && !/(auto|scroll)/.test(getComputedStyle(box).overflowY)) box = box.parentElement;
+  if (!box || box.scrollHeight <= box.clientHeight) return;
+  const area = box.getBoundingClientRect();
+  const rect = item.getBoundingClientRect();
+  if (rect.top < area.top) box.scrollTop -= area.top - rect.top;
+  else if (rect.bottom > area.bottom) box.scrollTop += Math.min(rect.bottom - area.bottom, rect.top - area.top);
+}
+
+function noop() {}