diff --git a/src/modules/markdown/components/callout.tsx b/src/modules/markdown/components/callout.tsx
index 6907d85..1a96e0d 100644
--- a/src/modules/markdown/components/callout.tsx
+++ b/src/modules/markdown/components/callout.tsx
@@ -5,7 +5,7 @@ import {
   OctagonAlertIcon,
   TriangleAlertIcon,
 } from 'lucide-react';
-import type { ReactNode } from 'react';
+import * as React from 'react';
 
 /**
  * The five GitHub alert types, each mapped to its icon and visible label.
@@ -31,7 +31,7 @@ type AlertType = keyof typeof ALERTS;
  * @param props.type - One of the five alert types; supplied by `remark-alert`.
  * @param props.children - The alert body, already stripped of its `[!TYPE]` marker.
  */
-export function Callout({ type, children }: { type: AlertType; children: ReactNode }) {
+export function Callout({ type, children }: { type: AlertType; children: React.ReactNode }) {
   const { icon: Icon, label } = ALERTS[type];
   return (
     <div data-callout={type}>
diff --git a/src/modules/markdown/components/code-copy-button.tsx b/src/modules/markdown/components/code-copy-button.tsx
index 407588b..9bf3dea 100644
--- a/src/modules/markdown/components/code-copy-button.tsx
+++ b/src/modules/markdown/components/code-copy-button.tsx
@@ -1,8 +1,7 @@
 'use client';
 
 import { CheckIcon, CopyIcon } from 'lucide-react';
-import type { MouseEvent } from 'react';
-import { useRef, useState } from 'react';
+import * as React from 'react';
 
 import { Button } from '#/ui/components/core/button';
 
@@ -17,10 +16,10 @@ const COPY_FEEDBACK_DURATION_MS = 2000;
  * lines are skipped here.
  */
 export function CodeCopyButton() {
-  const [copied, setCopied] = useState(false);
-  const timeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const [copied, setCopied] = React.useState(false);
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout>>(undefined);
 
-  function handleCopy(event: MouseEvent<HTMLButtonElement>) {
+  function handleCopy(event: React.MouseEvent<HTMLButtonElement>) {
     const figure = event.currentTarget.closest('figure');
     if (!figure) return;
 
diff --git a/src/modules/markdown/components/tabs.tsx b/src/modules/markdown/components/tabs.tsx
index e77e3fb..35b9e70 100644
--- a/src/modules/markdown/components/tabs.tsx
+++ b/src/modules/markdown/components/tabs.tsx
@@ -1,7 +1,4 @@
-'use client';
-
-import type { ReactNode } from 'react';
-import { Children, isValidElement } from 'react';
+import * as React from 'react';
 
 import { Tabs as TabsRoot, TabsContent, TabsList, TabsTrigger } from '#/ui/components/core/tabs';
 
@@ -11,9 +8,9 @@ import { Tabs as TabsRoot, TabsContent, TabsList, TabsTrigger } from '#/ui/compo
  * remark plugin are plain strings; children hold one wrapper div per
  * `::tab[Label]` section, in label order.
  */
-export function Tabs({ labels, children }: { labels: string; children: ReactNode }) {
+export function Tabs({ labels, children }: { labels: string; children: React.ReactNode }) {
   const tabLabels = JSON.parse(labels) as string[];
-  const panels = Children.toArray(children).filter((child) => isValidElement(child));
+  const panels = React.Children.toArray(children).filter((child) => React.isValidElement(child));
 
   return (
     <TabsRoot defaultValue={0} data-tabs>
diff --git a/src/modules/toc/components/article-toc.tsx b/src/modules/toc/components/article-toc.tsx
new file mode 100644
index 0000000..85b5f9a
--- /dev/null
+++ b/src/modules/toc/components/article-toc.tsx
@@ -0,0 +1,160 @@
+import { ListIcon } from 'lucide-react';
+import * as React from 'react';
+
+import type { TableOfContents } from '#/modules/markdown/markdown.types';
+import { TocLink, TocList, TocRail, TocRoot, useToc } from '#/modules/toc/components/toc';
+import { parseTocEntries } from '#/modules/toc/toc.entries';
+import { Button } from '#/ui/components/core/button';
+import {
+  Drawer,
+  DrawerClose,
+  DrawerContent,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerTrigger,
+} from '#/ui/components/core/drawer';
+import {
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+} from '#/ui/components/core/sheet';
+import { cn } from '#/ui/utils';
+
+/**
+ * The article's "On this page" navigation, placed once per article and adapting
+ * to three widths:
+ *
+ * - **Desktop** (`xl` and up): fixed in the gutter just right of the centered
+ *   article, always visible ({@link GutterToc}).
+ * - **Tablet** (`md`–`xl`, where that gutter collapses): a floating button
+ *   opening the list in a right-side sheet ({@link SheetToc}).
+ * - **Mobile** (below `md`): a full-width bar pinned to the very bottom like a
+ *   bottom navigation bar, opening the list in a drawer ({@link DrawerToc}).
+ *
+ * All three tiers share one {@link TocRoot}, so the reading position is
+ * tracked once no matter which tier is visible. Renders nothing when the
+ * article has no h2/h3 headings.
+ */
+export function ArticleToc({ headings }: { headings: TableOfContents }) {
+  const entries = React.useMemo(() => parseTocEntries(headings), [headings]);
+  if (entries.length === 0) return null;
+
+  return (
+    <TocRoot entries={entries}>
+      <GutterToc />
+      <div className="hidden md:block xl:hidden">
+        <SheetToc />
+      </div>
+      <div className="md:hidden">
+        <DrawerToc />
+      </div>
+    </TocRoot>
+  );
+}
+
+const TOC_TITLE = 'On this page';
+
+/** The icon-and-text title shared by every tier's heading. */
+function TocTitle() {
+  return (
+    <>
+      <ListIcon className="text-muted-foreground size-4" aria-hidden />
+      {TOC_TITLE}
+    </>
+  );
+}
+
+/**
+ * The scrollable list every tier shows: rail, links, and the fading
+ * `.toc-scroll` viewport (see app.css) that hides its scrollbar and fades the
+ * edges while there's more to scroll.
+ */
+function TocPanel({ className, onNavigate }: { className?: string; onNavigate?: () => void }) {
+  const { entries } = useToc();
+
+  return (
+    <div className={cn('toc-scroll min-h-0 overflow-y-auto', className)}>
+      <TocList onNavigate={onNavigate}>
+        <TocRail />
+        {entries.map((entry) => (
+          <TocLink key={entry.id} entry={entry} />
+        ))}
+      </TocList>
+    </div>
+  );
+}
+
+/** Desktop tier: always visible in the gutter right of the centered article. */
+function GutterToc() {
+  return (
+    <aside className="fixed top-8 left-[calc(50%+23rem)] hidden max-h-[calc(100vh-4rem)] w-56 flex-col xl:flex">
+      <p className="text-muted-foreground mb-3 flex shrink-0 items-center gap-2 text-sm">
+        <TocTitle />
+      </p>
+      <TocPanel />
+    </aside>
+  );
+}
+
+/**
+ * Tablet tier: a floating outline button in the bottom-right corner opening
+ * the TOC in a sheet that slides in from the right, echoing the desktop
+ * gutter's position. Closes as soon as a link scrolls the page.
+ */
+function SheetToc() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Sheet open={open} onOpenChange={setOpen}>
+      <SheetTrigger
+        className="fixed right-4 bottom-6 z-40 shadow-md"
+        render={
+          <Button variant="secondary">
+            <ListIcon aria-hidden /> {TOC_TITLE}
+          </Button>
+        }
+      />
+      <SheetContent side="right" className="w-80">
+        <SheetHeader>
+          <SheetTitle className="flex items-center gap-2">
+            <TocTitle />
+          </SheetTitle>
+        </SheetHeader>
+        <TocPanel className="flex-1 px-4 pb-4" onNavigate={() => setOpen(false)} />
+      </SheetContent>
+    </Sheet>
+  );
+}
+
+/**
+ * Mobile tier: a full-width bar fixed to the very bottom — styled like a
+ * mobile bottom navigation bar, with a safe-area inset so it clears the home
+ * indicator — opening the TOC in a bottom drawer the reader can swipe down to
+ * dismiss. Closes as soon as a link scrolls the page.
+ */
+function DrawerToc() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Drawer open={open} onOpenChange={setOpen} showSwipeHandle>
+      <DrawerTrigger className="bg-background/90 text-foreground supports-backdrop-filter:bg-background/75 fixed inset-x-0 bottom-0 z-40 flex items-center justify-center gap-2 border-t px-4 pt-3.5 pb-[max(0.875rem,env(safe-area-inset-bottom))] text-sm font-medium shadow-[0_-1px_3px_rgb(0_0_0/0.04)] backdrop-blur">
+        <ListIcon className="text-muted-foreground size-4" aria-hidden />
+        {TOC_TITLE}
+      </DrawerTrigger>
+      <DrawerContent className="[--drawer-content-max-height:70dvh]">
+        <DrawerHeader>
+          <DrawerTitle className="flex items-center justify-center gap-2 text-base">
+            <TocTitle />
+          </DrawerTitle>
+        </DrawerHeader>
+        <TocPanel className="mt-4 flex-1 px-4 pb-4" onNavigate={() => setOpen(false)} />
+        <DrawerFooter className="border-t pt-4 pb-[max(1rem,env(safe-area-inset-bottom))]">
+          <DrawerClose render={<Button variant="secondary" />}>Close</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>
+  );
+}
diff --git a/src/modules/toc/components/toc.tsx b/src/modules/toc/components/toc.tsx
new file mode 100644
index 0000000..62c60e7
--- /dev/null
+++ b/src/modules/toc/components/toc.tsx
@@ -0,0 +1,240 @@
+import * as React from 'react';
+
+import type { TocEntry } from '#/modules/toc/toc.entries';
+import type { RailGeometry } from '#/modules/toc/toc.rail';
+import { DOT_RADIUS, highlightSpan, linkIndent, useRailGeometry } from '#/modules/toc/toc.rail';
+import { scrollToHeading, useKeepActiveInView, useScrollSpy } from '#/modules/toc/toc.scroll';
+import { cn } from '#/ui/utils';
+
+/**
+ * Composable "On this page" primitives. `TocRoot` owns the shared reading
+ * state (one scroll spy, however many lists render under it); each `TocList`
+ * renders one navigable list and measures its own layout for the `TocRail`
+ * highlight. Compose them per surface:
+ *
+ * ```tsx
+ * const entries = parseTocEntries(post.toc);
+ *
+ * <TocRoot entries={entries}>
+ *   <TocList onNavigate={close}>
+ *     <TocRail />
+ *     {entries.map((entry) => (
+ *       <TocLink key={entry.id} entry={entry} />
+ *     ))}
+ *   </TocList>
+ * </TocRoot>
+ * ```
+ *
+ * `ArticleToc` assembles these into the standard responsive shell.
+ */
+
+interface TocContextValue {
+  /** The entries this TOC navigates, in document order. */
+  entries: TocEntry[];
+  /** Ids of the headings whose section is on screen, in document order. */
+  activeIds: string[];
+  /** The reading position is still above the first heading. */
+  atStart: boolean;
+  /** The end of the article's content has scrolled into view. */
+  atEnd: boolean;
+}
+
+const TocContext = React.createContext<TocContextValue | null>(null);
+
+/** The TOC's entries and live reading state, provided by {@link TocRoot}. */
+export function useToc(): TocContextValue {
+  const context = React.useContext(TocContext);
+  if (!context) throw new Error('useToc must be used within <TocRoot>');
+  return context;
+}
+
+interface TocRootProps {
+  /**
+   * Parsed entries (see `parseTocEntries`), referentially stable across
+   * renders — memoize at the call site; they key the scroll spy.
+   */
+  entries: TocEntry[];
+  children: React.ReactNode;
+}
+
+/**
+ * Provides the entries and their scroll-derived reading state to every TOC
+ * piece below it. Renders no DOM of its own, so one root can feed several
+ * lists (the responsive shell mounts three) from a single scroll listener.
+ */
+export function TocRoot({ entries, children }: TocRootProps) {
+  const spy = useScrollSpy(entries);
+  const value = React.useMemo(() => ({ entries, ...spy }), [entries, spy]);
+  return <TocContext.Provider value={value}>{children}</TocContext.Provider>;
+}
+
+interface TocListContextValue {
+  /** Measured layout of this list, or `null` until it has one (see `useRailGeometry`). */
+  geometry: RailGeometry | null;
+  /** Registers a link's `<li>` under its entry id, for measurement and follow-scroll. */
+  registerLink: (id: string, element: HTMLLIElement | null) => void;
+  /** Click handler shared by every link: smooth-scrolls and reports navigation. */
+  onLinkClick: (event: React.MouseEvent<HTMLAnchorElement>, id: string) => void;
+}
+
+const TocListContext = React.createContext<TocListContextValue | null>(null);
+
+function useTocList(): TocListContextValue {
+  const context = React.useContext(TocListContext);
+  if (!context) throw new Error('TOC list pieces must be used within <TocList>');
+  return context;
+}
+
+interface TocListProps {
+  className?: string;
+  /** Called after a link scrolls the page — lets a sheet or drawer close. */
+  onNavigate?: () => void;
+  /** `TocLink`s (and optionally a `TocRail`). */
+  children: React.ReactNode;
+}
+
+/**
+ * One rendered TOC list: a `<nav>` around a `<ul>` of {@link TocLink}s. Owns
+ * everything tied to this particular list instance — measuring its layout for
+ * the rail, keeping the active link centered when the list scrolls, and
+ * closing over `onNavigate` for its links — while the reading state comes from
+ * the shared {@link TocRoot} above.
+ */
+export function TocList({ className, onNavigate, children }: TocListProps) {
+  const { entries, activeIds } = useToc();
+  const listRef = React.useRef<HTMLUListElement>(null);
+  const linkRefs = React.useRef<Map<string, HTMLLIElement>>(new Map());
+
+  const geometry = useRailGeometry(listRef, linkRefs, entries);
+  useKeepActiveInView(linkRefs, activeIds[0]);
+
+  const registerLink = React.useCallback((id: string, element: HTMLLIElement | null) => {
+    if (element) linkRefs.current.set(id, element);
+    else linkRefs.current.delete(id);
+  }, []);
+
+  const onLinkClick = React.useCallback(
+    (event: React.MouseEvent<HTMLAnchorElement>, id: string) => {
+      const heading = document.getElementById(id);
+      if (!heading) return; // fall back to the browser's default hash jump
+      event.preventDefault();
+      scrollToHeading(heading);
+      onNavigate?.();
+    },
+    [onNavigate],
+  );
+
+  const value = React.useMemo(
+    () => ({ geometry, registerLink, onLinkClick }),
+    [geometry, registerLink, onLinkClick],
+  );
+
+  return (
+    <nav aria-label="On this page" className={cn('relative text-sm', className)}>
+      <TocListContext.Provider value={value}>
+        {/* The list is the links' offset parent — rail coordinates hang off it. */}
+        <ul ref={listRef} className="relative p-1">
+          {children}
+        </ul>
+      </TocListContext.Provider>
+    </nav>
+  );
+}
+
+interface TocLinkProps {
+  entry: TocEntry;
+  /** Custom label content; defaults to the entry's heading text. */
+  children?: React.ReactNode;
+}
+
+/**
+ * One entry's link. Highlights itself while its section is on screen and
+ * registers its element with the surrounding {@link TocList} so the rail and
+ * follow-scroll know where it sits.
+ */
+export function TocLink({ entry, children }: TocLinkProps) {
+  const { activeIds } = useToc();
+  const { registerLink, onLinkClick } = useTocList();
+
+  return (
+    <li
+      ref={(element) => {
+        registerLink(entry.id, element);
+      }}
+    >
+      <a
+        href={`#${entry.id}`}
+        data-active={activeIds.includes(entry.id) || undefined}
+        onClick={(event) => onLinkClick(event, entry.id)}
+        style={{ paddingLeft: linkIndent(entry.level) }}
+        className="text-muted-foreground hover:text-foreground data-active:text-foreground block py-1.5 leading-snug transition-colors"
+      >
+        {children ?? entry.label}
+      </a>
+    </li>
+  );
+}
+
+/**
+ * The rail behind the list: a faint track — a line threading every link plus a
+ * dot at each end — under an identical accented copy clipped with an animated
+ * inset `clip-path` to the active span. Animating only the clip inset (not the
+ * geometry) lets the highlight glide along the shared curve, and — since the
+ * dots live in the clipped copy too — morph continuously between dot and line
+ * at the boundaries. The technique from fuma-nama.dev's SVG posts, recolored
+ * to this project's monochrome palette.
+ *
+ * Rendered as an absolutely positioned list item so it can sit inside the
+ * `<ul>` — aligned with the coordinate space the links are measured in —
+ * without affecting layout or the accessibility tree. Renders nothing until
+ * the list has been measured.
+ */
+export function TocRail() {
+  const { activeIds, atStart, atEnd } = useToc();
+  const { geometry } = useTocList();
+  if (!geometry) return null;
+
+  const highlight = highlightSpan(geometry, { activeIds, atStart, atEnd });
+
+  return (
+    <li aria-hidden className="pointer-events-none absolute inset-0">
+      <svg
+        width={geometry.width}
+        height={geometry.height}
+        viewBox={`0 0 ${geometry.width} ${geometry.height}`}
+        fill="none"
+        className="overflow-visible"
+      >
+        <RailShape geometry={geometry} className="text-border" />
+        {highlight && (
+          <g
+            className="transition-[clip-path] duration-300 ease-out motion-reduce:transition-none"
+            // `view-box` measures the inset from the SVG's coordinates (the
+            // default box is this group's bounding box, inflated by the dots);
+            // the negative insets reach the dots' overhang past the viewBox.
+            style={{
+              clipPath: `inset(${highlight.top}px ${-DOT_RADIUS}px ${geometry.height - highlight.bottom}px ${-DOT_RADIUS}px) view-box`,
+            }}
+          >
+            <RailShape geometry={geometry} className="text-foreground" />
+          </g>
+        )}
+      </svg>
+    </li>
+  );
+}
+
+/**
+ * One monochrome copy of the rail's shape — track plus boundary dots — colored
+ * by `className` through `currentColor`. The rail layers two of these, so the
+ * base and its clipped accent can never drift apart.
+ */
+function RailShape({ geometry, className }: { geometry: RailGeometry; className: string }) {
+  return (
+    <g className={className}>
+      <path d={geometry.path} strokeWidth={1} stroke="currentColor" />
+      <circle cx={geometry.start.x} cy={geometry.start.y} r={DOT_RADIUS} fill="currentColor" />
+      <circle cx={geometry.end.x} cy={geometry.end.y} r={DOT_RADIUS} fill="currentColor" />
+    </g>
+  );
+}
diff --git a/src/modules/toc/toc.entries.ts b/src/modules/toc/toc.entries.ts
new file mode 100644
index 0000000..abac518
--- /dev/null
+++ b/src/modules/toc/toc.entries.ts
@@ -0,0 +1,41 @@
+import type { TableOfContents } from '#/modules/markdown/markdown.types';
+
+/**
+ * One entry of the rendered table of contents: a heading the reader can jump
+ * to. `level` is indentation depth, not the raw heading depth — the shallowest
+ * kept heading sits at 0, so a document whose headings start at `h3` still
+ * renders flush-left instead of pre-indented.
+ */
+export interface TocEntry {
+  /** Slug of the rendered heading element — deep-link to it with `#${id}`. */
+  id: string;
+  /** The heading's plain text, shown as the link label. */
+  label: string;
+  /** Indentation depth: 0 for the shallowest kept heading. */
+  level: number;
+}
+
+// Only h2/h3 make the cut — deeper headings would over-nest the narrow
+// gutter, and h1 is the page title, rendered outside the MDX body.
+const MIN_DEPTH = 2;
+const MAX_DEPTH = 3;
+
+/**
+ * Turns a document's raw headings into renderable {@link TocEntry} items:
+ * keeps the h2/h3 headings and normalizes their depth to a 0-based `level`
+ * relative to the shallowest heading present. Returns `[]` when nothing
+ * qualifies, so callers can skip the TOC entirely rather than render an empty
+ * shell.
+ */
+export function parseTocEntries(headings: TableOfContents): TocEntry[] {
+  const kept = headings.filter(
+    (heading) => heading.depth >= MIN_DEPTH && heading.depth <= MAX_DEPTH,
+  );
+  if (kept.length === 0) return [];
+  const minDepth = Math.min(...kept.map((heading) => heading.depth));
+  return kept.map((heading) => ({
+    id: heading.id,
+    label: heading.title,
+    level: heading.depth - minDepth,
+  }));
+}
diff --git a/src/modules/toc/toc.rail.ts b/src/modules/toc/toc.rail.ts
new file mode 100644
index 0000000..5d78e9f
--- /dev/null
+++ b/src/modules/toc/toc.rail.ts
@@ -0,0 +1,197 @@
+import * as React from 'react';
+
+import type { TocEntry } from '#/modules/toc/toc.entries';
+import type { ScrollSpyState } from '#/modules/toc/toc.scroll';
+
+/** A point along the rail, in px, in the SVG's coordinate space. */
+export interface RailPoint {
+  x: number;
+  y: number;
+}
+
+/** A vertical span along the rail, in px. */
+export interface RailSpan {
+  top: number;
+  bottom: number;
+}
+
+/** One link's slice of the rail: its column `x` and vertical extent, in px. */
+export interface RailSlot {
+  id: string;
+  x: number;
+  top: number;
+  bottom: number;
+}
+
+/** Measured layout of a rendered TOC list, in px, driving the SVG rail. */
+export interface RailGeometry {
+  width: number;
+  height: number;
+  /** SVG path threading through every slot — the full-length track. */
+  path: string;
+  /** Where the track begins and ends — the boundary dots sit here. */
+  start: RailPoint;
+  end: RailPoint;
+  /** Per rendered link, in list order. */
+  slots: RailSlot[];
+}
+
+// Geometry of the SVG rail, in px (its viewBox maps 1:1 to rendered pixels).
+// The rail sits in each link's left padding; both step right by LEVEL_INDENT
+// per level so the line and the text indent together.
+const RAIL_X_BASE = 3;
+const LINK_INDENT_BASE = 18;
+const LEVEL_INDENT = 12;
+
+/** Horizontal position of the rail for a heading at `level`. */
+export function railX(level: number): number {
+  return RAIL_X_BASE + level * LEVEL_INDENT;
+}
+
+/** Left padding of a TOC link at `level`, keeping its text clear of the rail. */
+export function linkIndent(level: number): number {
+  return LINK_INDENT_BASE + level * LEVEL_INDENT;
+}
+
+// How far, in px, the diagonal that steps between columns extends above and
+// below the shared edge between two links. Keeping the bend this close to the
+// edge lets the highlight pull in by the same amount to hide a bend into an
+// inactive neighbor (see highlightSpan below). Capped so the diagonal never
+// reaches past either link's midline when links are short.
+const BEND_INSET = 8;
+
+/**
+ * Builds the SVG path that threads through each slot's vertical extent in
+ * order. Runs between links at the same indent are straight verticals; a step
+ * to a different indent stays vertical until just above the links' shared
+ * edge, cuts across on a straight diagonal centered on that edge, then resumes
+ * vertical just below it. The segments meet at sharp corners — no rounding —
+ * so the bend reads as a crisp edge rather than a curve.
+ */
+export function buildRailPath(slots: RailSlot[]): string {
+  if (slots.length === 0) return '';
+  let path = `M${slots[0].x} ${slots[0].top}`;
+  for (let i = 0; i < slots.length; i++) {
+    const slot = slots[i];
+    const next = slots[i + 1];
+    if (!next || next.x === slot.x) {
+      path += ` L${slot.x} ${slot.bottom}`;
+      continue;
+    }
+    const edge = (slot.bottom + next.top) / 2;
+    const inset = Math.min(BEND_INSET, (edge - slot.top) * 0.4, (next.bottom - edge) * 0.4);
+    path += ` L${slot.x} ${edge - inset} L${next.x} ${edge + inset}`;
+  }
+  return path;
+}
+
+/** Radius, in px, of the dots terminating the rail. */
+export const DOT_RADIUS = 2.5;
+
+/** The span a boundary dot occupies around its center `y`. */
+function dotSpan(y: number): RailSpan {
+  return { top: y - DOT_RADIUS, bottom: y + DOT_RADIUS };
+}
+
+/**
+ * Vertical span of the rail to accent, or `null` when nothing is active.
+ * The active links' span pulls in by `BEND_INSET` at both ends: the rail's
+ * bends sit within that distance of the edge between two links, so a lone
+ * active link reads as a straight line and a bend only shows when the links on
+ * both of its sides are active. Trimming both ends unconditionally — not just
+ * beside a bend — keeps every highlight the same height and centered on its
+ * links regardless of the neighbors' indent.
+ *
+ * While a boundary state holds, the span stretches over that end's dot, so the
+ * highlight morphs continuously between dot and line as the reader crosses the
+ * article's edges. The spans are contiguous by construction — a lit dot always
+ * abuts the active range — so one window covers them all.
+ */
+export function highlightSpan(geometry: RailGeometry, spy: ScrollSpyState): RailSpan | null {
+  const activeIds = new Set(spy.activeIds);
+  const activeSlots = geometry.slots.filter((slot) => activeIds.has(slot.id));
+
+  const spans: RailSpan[] = [];
+  if (spy.atStart) spans.push(dotSpan(geometry.start.y));
+  if (activeSlots.length > 0) {
+    const first = activeSlots[0];
+    const last = activeSlots[activeSlots.length - 1];
+    spans.push({ top: first.top + BEND_INSET, bottom: last.bottom - BEND_INSET });
+  }
+  if (spy.atEnd) spans.push(dotSpan(geometry.end.y));
+
+  if (spans.length === 0) return null;
+  return { top: spans[0].top, bottom: spans[spans.length - 1].bottom };
+}
+
+/**
+ * Measures a rendered TOC list to produce the {@link RailGeometry} driving the
+ * SVG rail. The layout only exists after mount, so the geometry starts `null`
+ * — callers render just the links until then, keeping server and first client
+ * render identical — and is re-measured on reflow (fonts loading, breakpoint
+ * changes toggling a tier between `display:none` and visible).
+ *
+ * `list` must be the links' offset parent (position it), and `linkRefs` maps
+ * each entry's id to its rendered `<li>`; entries without a rendered link are
+ * skipped, so a list rendering a subset of entries still gets a correct rail.
+ */
+export function useRailGeometry(
+  listRef: React.RefObject<HTMLElement | null>,
+  linkRefs: React.RefObject<Map<string, HTMLElement>>,
+  entries: TocEntry[],
+): RailGeometry | null {
+  const [geometry, setGeometry] = React.useState<RailGeometry | null>(null);
+
+  React.useEffect(() => {
+    const list = listRef.current;
+    if (!list || entries.length === 0) {
+      setGeometry(null);
+      return;
+    }
+
+    const measure = () => {
+      // A hidden tier (the responsive shell keeps two of its three tiers
+      // display:none) measures 0×0 — report no geometry rather than a
+      // degenerate rail; the observer re-measures once it becomes visible.
+      if (list.offsetHeight === 0) {
+        setGeometry(null);
+        return;
+      }
+
+      const slots: RailSlot[] = [];
+      for (const entry of entries) {
+        const link = linkRefs.current.get(entry.id);
+        if (!link) continue;
+        slots.push({
+          id: entry.id,
+          x: railX(entry.level),
+          top: link.offsetTop,
+          bottom: link.offsetTop + link.offsetHeight,
+        });
+      }
+      if (slots.length === 0) {
+        setGeometry(null);
+        return;
+      }
+
+      const first = slots[0];
+      const last = slots[slots.length - 1];
+      setGeometry({
+        width: list.offsetWidth,
+        height: list.offsetHeight,
+        path: buildRailPath(slots),
+        start: { x: first.x, y: first.top },
+        end: { x: last.x, y: last.bottom },
+        slots,
+      });
+    };
+
+    // ResizeObserver delivers an initial notification on observe(), which
+    // performs the first measure; reflows re-run it from live layout.
+    const observer = new ResizeObserver(measure);
+    observer.observe(list);
+    return () => observer.disconnect();
+  }, [listRef, linkRefs, entries]);
+
+  return geometry;
+}
diff --git a/src/modules/toc/toc.scroll.ts b/src/modules/toc/toc.scroll.ts
new file mode 100644
index 0000000..cb4a5a7
--- /dev/null
+++ b/src/modules/toc/toc.scroll.ts
@@ -0,0 +1,190 @@
+import * as React from 'react';
+
+import type { TocEntry } from '#/modules/toc/toc.entries';
+
+/** What the reader can currently see, derived from the window scroll position. */
+export interface ScrollSpyState {
+  /** Ids of the headings whose section is on screen, in document order. */
+  activeIds: string[];
+  /** The reading position is still above the first heading (the intro). */
+  atStart: boolean;
+  /** The end of the article's content has scrolled into view. */
+  atEnd: boolean;
+}
+
+const NOTHING_VISIBLE: ScrollSpyState = { activeIds: [], atStart: false, atEnd: false };
+
+function prefersReducedMotion(): boolean {
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/** Whether two spy states hold the same boundary flags and ids, in order. */
+function sameSpyState(a: ScrollSpyState, b: ScrollSpyState): boolean {
+  return (
+    a.atStart === b.atStart &&
+    a.atEnd === b.atEnd &&
+    a.activeIds.length === b.activeIds.length &&
+    a.activeIds.every((id, index) => id === b.activeIds[index])
+  );
+}
+
+/**
+ * One measurement of the reading position, from live layout.
+ *
+ * A heading's section runs from its own top down to the next heading's top —
+ * and the last section down to the end of the article — so the sections tile
+ * the whole content region. A heading is active while its section overlaps the
+ * active band: the viewport, inset at the top so a heading that was just
+ * scrolled to (via a TOC link or `#` fragment) reads as active immediately
+ * instead of the section above it staying highlighted a moment longer. The
+ * inset is derived from the heading's `scroll-margin-top` (see markdown.css),
+ * doubled to clear it with room to spare.
+ *
+ * Above the first heading or below the article's content no section overlaps,
+ * so `activeIds` is empty: the highlight only shows while article content is
+ * actually on screen. Alongside it, the two boundary states: `atStart` while
+ * the reading position is still above the first heading, and `atEnd` once the
+ * article's content bottom has scrolled into the viewport — the reader can see
+ * the end. Either can overlap with active headings.
+ */
+function measureScrollSpy(ids: string[]): ScrollSpyState {
+  const viewportHeight = window.innerHeight;
+  const firstHeading = document.getElementById(ids[0]);
+  const headingTops = ids.map((id) => {
+    const heading = document.getElementById(id);
+    return heading ? heading.getBoundingClientRect().top : Number.POSITIVE_INFINITY;
+  });
+
+  // Top edge of the active band. Falls back to the viewport edge when the
+  // first heading isn't in the DOM yet, matching the `article` fallback below.
+  const bandTop = firstHeading ? parseFloat(getComputedStyle(firstHeading).scrollMarginTop) * 2 : 0;
+
+  // Cap the last heading's section at the end of the article so the highlight
+  // clears once the content scrolls out of view, instead of clinging to the
+  // final heading while the footer below it is on screen. Falls back to
+  // +Infinity if the article wrapper isn't found, extending the last section
+  // indefinitely.
+  const article = firstHeading?.closest('article');
+  const contentBottom = article ? article.getBoundingClientRect().bottom : Number.POSITIVE_INFINITY;
+
+  const activeIds: string[] = [];
+  for (let i = 0; i < ids.length; i++) {
+    const sectionTop = headingTops[i];
+    const sectionBottom = i + 1 < ids.length ? headingTops[i + 1] : contentBottom;
+    // The section [sectionTop, sectionBottom) overlaps the band [bandTop, viewportHeight).
+    if (sectionTop < viewportHeight && sectionBottom > bandTop) activeIds.push(ids[i]);
+  }
+
+  return {
+    activeIds,
+    atStart: headingTops[0] > bandTop,
+    atEnd: contentBottom <= viewportHeight,
+  };
+}
+
+/**
+ * Tracks which headings' sections are currently on screen (see
+ * {@link measureScrollSpy}), in document order, so the TOC can highlight the
+ * full visible range rather than a single anchor.
+ *
+ * Reads live layout on scroll/resize (coalesced into an animation frame)
+ * instead of caching offsets, so it stays correct as images load and reflow
+ * the article. `entries` must be referentially stable across renders (memoize
+ * at the call site) — it keys the effect.
+ */
+export function useScrollSpy(entries: TocEntry[]): ScrollSpyState {
+  const [spy, setSpy] = React.useState<ScrollSpyState>(NOTHING_VISIBLE);
+
+  React.useEffect(() => {
+    if (entries.length === 0) {
+      setSpy(NOTHING_VISIBLE);
+      return;
+    }
+
+    const ids = entries.map((entry) => entry.id);
+    let frame = 0;
+
+    const update = () => {
+      frame = 0;
+      const next = measureScrollSpy(ids);
+      setSpy((previous) => (sameSpyState(previous, next) ? previous : next));
+    };
+
+    const schedule = () => {
+      if (!frame) frame = requestAnimationFrame(update);
+    };
+
+    update();
+    window.addEventListener('scroll', schedule, { passive: true });
+    window.addEventListener('resize', schedule);
+    return () => {
+      window.removeEventListener('scroll', schedule);
+      window.removeEventListener('resize', schedule);
+      if (frame) cancelAnimationFrame(frame);
+    };
+  }, [entries]);
+
+  return spy;
+}
+
+/** The nearest ancestor that actually scrolls vertically, or null if none does. */
+function scrollableAncestor(element: HTMLElement): HTMLElement | null {
+  for (let node = element.parentElement; node; node = node.parentElement) {
+    const overflowY = getComputedStyle(node).overflowY;
+    if ((overflowY === 'auto' || overflowY === 'scroll') && node.scrollHeight > node.clientHeight) {
+      return node;
+    }
+  }
+  return null;
+}
+
+/**
+ * Keeps the active TOC link centered in its own scroll container. A long
+ * article's list can outgrow the fixed desktop aside (or the sheet/drawer), so
+ * as the reader scrolls the page the container scrolls in step to hold the
+ * highlighted link on its vertical midline. The browser clamps this at the
+ * ends, so the first and last links still rest against the container's edges
+ * rather than being forced past them to reach the center.
+ *
+ * Scrolls only the nearest scrollable ancestor — never the window — so keeping
+ * pace with the reader inside the gutter can't nudge the article's own scroll
+ * position. A no-op while the list fits (the ancestor search skips containers
+ * tall enough to show everything) and while nothing is active (`activeId` of
+ * `undefined`).
+ */
+export function useKeepActiveInView(
+  linkRefs: React.RefObject<Map<string, HTMLElement>>,
+  activeId: string | undefined,
+): void {
+  React.useEffect(() => {
+    if (!activeId) return;
+    const link = linkRefs.current.get(activeId);
+    if (!link) return;
+
+    const container = scrollableAncestor(link);
+    if (!container) return;
+
+    const linkRect = link.getBoundingClientRect();
+    const containerRect = container.getBoundingClientRect();
+    // Shift the container so the active link's midline meets the container's.
+    const delta =
+      linkRect.top + linkRect.height / 2 - (containerRect.top + container.clientHeight / 2);
+    if (Math.round(delta) === 0) return;
+
+    container.scrollBy({ top: delta, behavior: prefersReducedMotion() ? 'auto' : 'smooth' });
+  }, [linkRefs, activeId]);
+}
+
+/**
+ * Scrolls the page to a heading the way a TOC link should: smoothly (unless
+ * the reader prefers reduced motion) and with the URL hash updated in place —
+ * `replaceState`, not a navigation — so the address stays shareable without
+ * flooding history with a back-entry per visited heading.
+ */
+export function scrollToHeading(heading: HTMLElement): void {
+  heading.scrollIntoView({
+    behavior: prefersReducedMotion() ? 'auto' : 'smooth',
+    block: 'start',
+  });
+  history.replaceState(null, '', `#${heading.id}`);
+}
diff --git a/src/routes/posts/$slug.tsx b/src/routes/posts/$slug.tsx
index 7d6c18e..f16efcb 100644
--- a/src/routes/posts/$slug.tsx
+++ b/src/routes/posts/$slug.tsx
@@ -2,6 +2,7 @@ import { createFileRoute } from '@tanstack/react-router';
 
 import { getPostBySlugFn } from '#/modules/post/post.fn';
 import { ThumbnailFigure } from '#/modules/thumbnail/components/thumbnail-figure';
+import { ArticleToc } from '#/modules/toc/components/article-toc';
 import { Badge } from '#/ui/components/core/badge';
 import { Separator } from '#/ui/components/core/separator';
 
@@ -36,6 +37,7 @@ function PostPage() {
         <Separator className="my-6" />
         <div className="prose dark:prose-invert">{post.mdx}</div>
       </article>
+      <ArticleToc headings={post.toc} />
     </main>
   );
 }
diff --git a/src/routes/series/$slug/$postSlug.tsx b/src/routes/series/$slug/$postSlug.tsx
index 12cf8a3..88ad9d4 100644
--- a/src/routes/series/$slug/$postSlug.tsx
+++ b/src/routes/series/$slug/$postSlug.tsx
@@ -2,6 +2,7 @@ import { createFileRoute, Link } from '@tanstack/react-router';
 
 import { getSeriesPostFn } from '#/modules/series/series.fn';
 import { ThumbnailFigure } from '#/modules/thumbnail/components/thumbnail-figure';
+import { ArticleToc } from '#/modules/toc/components/article-toc';
 import { Badge } from '#/ui/components/core/badge';
 import { Separator } from '#/ui/components/core/separator';
 
@@ -44,6 +45,7 @@ function SeriesPostPage() {
         <Separator className="my-6" />
         <div className="prose dark:prose-invert">{post.mdx}</div>
       </article>
+      <ArticleToc headings={post.toc} />
     </main>
   );
 }
diff --git a/src/ui/components/core/field.tsx b/src/ui/components/core/field.tsx
index d18aaaf..07c67a7 100644
--- a/src/ui/components/core/field.tsx
+++ b/src/ui/components/core/field.tsx
@@ -1,5 +1,5 @@
 import { cva, type VariantProps } from 'class-variance-authority';
-import { useMemo } from 'react';
+import * as React from 'react';
 
 import { Label } from '#/ui/components/core/label';
 import { Separator } from '#/ui/components/core/separator';
@@ -170,7 +170,7 @@ function FieldError({
 }: React.ComponentProps<'div'> & {
   errors?: Array<{ message?: string } | undefined>;
 }) {
-  const content = useMemo(() => {
+  const content = React.useMemo(() => {
     if (children) {
       return children;
     }
diff --git a/src/ui/components/core/sheet.tsx b/src/ui/components/core/sheet.tsx
index 43f74df..2e86dc3 100644
--- a/src/ui/components/core/sheet.tsx
+++ b/src/ui/components/core/sheet.tsx
@@ -60,7 +60,7 @@ function SheetContent({
         {showCloseButton && (
           <SheetPrimitive.Close
             data-slot="sheet-close"
-            render={<Button variant="ghost" className="absolute top-4 right-4" size="icon-sm" />}
+            render={<Button variant="ghost" className="absolute top-3 right-3" size="icon-sm" />}
           >
             <XIcon />
             <span className="sr-only">Close</span>
diff --git a/src/ui/components/core/tabs.tsx b/src/ui/components/core/tabs.tsx
index 191e6f3..96e08d5 100644
--- a/src/ui/components/core/tabs.tsx
+++ b/src/ui/components/core/tabs.tsx
@@ -1,3 +1,5 @@
+'use client';
+
 import { Tabs as TabsPrimitive } from '@base-ui/react/tabs';
 import { cva, type VariantProps } from 'class-variance-authority';
 
diff --git a/src/ui/styles/app.css b/src/ui/styles/app.css
index a135d9f..1fc39fb 100644
--- a/src/ui/styles/app.css
+++ b/src/ui/styles/app.css
@@ -130,5 +130,77 @@
   }
   html {
     @apply font-sans;
+    scroll-behavior: smooth;
+  }
+  /* Honour reduced-motion for every anchor jump the way the TOC's JS already does. */
+  @media (prefers-reduced-motion: reduce) {
+    html {
+      scroll-behavior: auto;
+    }
+  }
+}
+
+/*
+ * Hide the scrollbar on the table-of-contents scroll areas (desktop gutter
+ * aside, tablet sheet, mobile drawer) while keeping them scrollable — the SVG
+ * rail already signals overflow, so a bar would just add visual noise.
+ */
+.toc-scroll {
+  scrollbar-width: none;
+}
+
+.toc-scroll::-webkit-scrollbar {
+  display: none;
+}
+
+/*
+ * Fade the top/bottom edges of the TOC scroll areas, but only while there's
+ * more to scroll in that direction. Two scroll-driven animations drive the
+ * fade lengths of a single mask gradient: the top fade grows in as you scroll
+ * away from the top, the bottom fade shrinks away as you approach the end. The
+ * lengths start at 0, so where scroll-driven animations aren't supported — or
+ * the list is short enough not to overflow — nothing fades.
+ */
+@property --toc-fade-top {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: 0px;
+}
+
+@property --toc-fade-bottom {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: 0px;
+}
+
+@supports (animation-timeline: scroll()) {
+  .toc-scroll {
+    --toc-fade: 8rem;
+    mask-image: linear-gradient(
+      to bottom,
+      transparent,
+      #000 var(--toc-fade-top),
+      #000 calc(100% - var(--toc-fade-bottom)),
+      transparent
+    );
+    animation:
+      toc-fade-top linear both,
+      toc-fade-bottom linear both;
+    animation-timeline: scroll(self block), scroll(self block);
+    animation-range:
+      0 var(--toc-fade),
+      calc(100% - var(--toc-fade)) 100%;
+  }
+
+  @keyframes toc-fade-top {
+    to {
+      --toc-fade-top: var(--toc-fade);
+    }
+  }
+
+  @keyframes toc-fade-bottom {
+    from {
+      --toc-fade-bottom: var(--toc-fade);
+    }
   }
 }
diff --git a/vite.config.ts b/vite.config.ts
index e658da0..b7fcf34 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -14,11 +14,16 @@ import { viteMdx } from '#/modules/markdown/markdown.vite';
 
 const config = defineConfig({
   resolve: { tsconfigPaths: true },
+  // lucide-react ships a `"use client"` directive on its Icon module, so the RSC
+  // graph treats it as a client boundary. Excluding it from the client dep
+  // optimizer keeps that boundary consistent and silences the rsc:use-client
+  // "inconsistently optimized" warning.
+  optimizeDeps: { exclude: ['lucide-react'] },
   server: { port: 3000 },
   preview: { port: 3000 },
   build: {
     target: 'esnext',
-    rollupOptions: {
+    rolldownOptions: {
       external: ['node:async_hooks', 'cloudflare:workers'],
     },
   },