From eddb5e67f077c1c76c3b2f89d18cb52d413f6e5b Mon Sep 17 00:00:00 2001
From: Andrew Hoang <hoangaatrox23504@gmail.com>
Date: Sun, 26 Jul 2026 21:51:43 +0700
Subject: [PATCH] docs: add TOC minimap + mobile nav and heading anchors

---
 .../(shell)/docs/components/asciify/page.tsx  |   1 +
 src/app/(shell)/docs/components/bend/page.tsx |   1 +
 .../(shell)/docs/components/blaze/page.tsx    |   1 +
 .../(shell)/docs/components/bubble/page.tsx   |   1 +
 .../(shell)/docs/components/cloth/page.tsx    |   1 +
 .../(shell)/docs/components/clouds/page.tsx   |   1 +
 .../docs/components/dithered-object/page.tsx  |   9 +-
 .../(shell)/docs/components/droplets/page.tsx |   1 +
 .../(shell)/docs/components/frost/page.tsx    |   1 +
 .../docs/components/glass-object/page.tsx     |   9 +-
 .../(shell)/docs/components/glass/page.tsx    |   1 +
 .../(shell)/docs/components/glitch/page.tsx   |   1 +
 src/app/(shell)/docs/components/grid/page.tsx |   1 +
 .../docs/components/hex-float/page.tsx        |   1 +
 .../(shell)/docs/components/laser/page.tsx    |  15 ++
 .../(shell)/docs/components/liquid/page.tsx   |   1 +
 .../(shell)/docs/components/magnify/page.tsx  |   1 +
 .../docs/components/particle-object/page.tsx  |   9 +-
 .../docs/components/particle-reveal/page.tsx  |  19 +-
 .../docs/components/particle-scroll/page.tsx  |   1 +
 src/app/(shell)/docs/components/peel/page.tsx |  19 +-
 .../docs/components/retro-dither/page.tsx     |   1 +
 .../(shell)/docs/components/ripple/page.tsx   |   1 +
 .../(shell)/docs/components/shatter/page.tsx  |   1 +
 src/app/(shell)/docs/components/vhs/page.tsx  |   1 +
 src/app/(shell)/layout.tsx                    |   5 +-
 src/components/docs/component-doc.tsx         | 220 ++++++++++--------
 src/components/docs/copy-button.tsx           |   6 +-
 src/components/docs/heading-anchor.tsx        |  66 ++++++
 src/components/docs/toc-layout.tsx            |  56 +++++
 src/components/docs/toc-minimap.tsx           | 165 +++++++++++++
 src/components/docs/toc-mobile.tsx            |  51 ++++
 src/components/ui/hover-card.tsx              |  53 +++++
 src/demos/demo-image-cycler.tsx               |  11 +-
 34 files changed, 625 insertions(+), 107 deletions(-)
 create mode 100644 src/components/docs/heading-anchor.tsx
 create mode 100644 src/components/docs/toc-layout.tsx
 create mode 100644 src/components/docs/toc-minimap.tsx
 create mode 100644 src/components/docs/toc-mobile.tsx
 create mode 100644 src/components/ui/hover-card.tsx

diff --git a/src/app/(shell)/docs/components/asciify/page.tsx b/src/app/(shell)/docs/components/asciify/page.tsx
index 6d76a59..34fc685 100644
--- a/src/app/(shell)/docs/components/asciify/page.tsx
+++ b/src/app/(shell)/docs/components/asciify/page.tsx
@@ -135,6 +135,7 @@ export default async function AsciifyPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Move your cursor over the photo to see how it reads as ascii characters."
diff --git a/src/app/(shell)/docs/components/bend/page.tsx b/src/app/(shell)/docs/components/bend/page.tsx
index f7eae2a..0efc277 100644
--- a/src/app/(shell)/docs/components/bend/page.tsx
+++ b/src/app/(shell)/docs/components/bend/page.tsx
@@ -121,6 +121,7 @@ export default async function BendPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Scroll to watch the photo bend over the fold along with the rest of the page."
diff --git a/src/app/(shell)/docs/components/blaze/page.tsx b/src/app/(shell)/docs/components/blaze/page.tsx
index cc1a165..24a63c1 100644
--- a/src/app/(shell)/docs/components/blaze/page.tsx
+++ b/src/app/(shell)/docs/components/blaze/page.tsx
@@ -121,6 +121,7 @@ export default async function BlazePage() {
         installItem="blaze"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Sweep your cursor across the photo to set it alight."
diff --git a/src/app/(shell)/docs/components/bubble/page.tsx b/src/app/(shell)/docs/components/bubble/page.tsx
index 85a87a1..736fb6e 100644
--- a/src/app/(shell)/docs/components/bubble/page.tsx
+++ b/src/app/(shell)/docs/components/bubble/page.tsx
@@ -158,6 +158,7 @@ export default async function BubblePage() {
         installItem="bubble"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Drag the droplet across the photo, then stop and watch it pool back together."
diff --git a/src/app/(shell)/docs/components/cloth/page.tsx b/src/app/(shell)/docs/components/cloth/page.tsx
index 62a56c2..9cc89be 100644
--- a/src/app/(shell)/docs/components/cloth/page.tsx
+++ b/src/app/(shell)/docs/components/cloth/page.tsx
@@ -134,6 +134,7 @@ export default async function ClothPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="This whole page is hanging on the fabric. Brush it with your cursor, and open the controls to change the wind."
diff --git a/src/app/(shell)/docs/components/clouds/page.tsx b/src/app/(shell)/docs/components/clouds/page.tsx
index b1ce64b..62ff522 100644
--- a/src/app/(shell)/docs/components/clouds/page.tsx
+++ b/src/app/(shell)/docs/components/clouds/page.tsx
@@ -154,6 +154,7 @@ export default async function CloudsPage() {
         installItem="clouds"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Watch the clouds drift across the photo, and push them around with your cursor."
diff --git a/src/app/(shell)/docs/components/dithered-object/page.tsx b/src/app/(shell)/docs/components/dithered-object/page.tsx
index 7485a7b..e09e2c2 100644
--- a/src/app/(shell)/docs/components/dithered-object/page.tsx
+++ b/src/app/(shell)/docs/components/dithered-object/page.tsx
@@ -5,6 +5,7 @@ import { Footer } from "@/components/landing/footer";
 import type { ApiProp } from "@/components/docs/api-reference";
 import { getComponentSources } from "@/lib/registry";
 import { highlight } from "@/components/docs/highlight";
+import { HeadingAnchor } from "@/components/docs/heading-anchor";
 import { DitheredObjectDemo } from "@/demos/dithered-object-demo";
 
 export const metadata: Metadata = {
@@ -204,9 +205,15 @@ export default async function DitheredObjectPage() {
         installItem="dithered-object"
         tags={["webgl", "three.js", "3D"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <section className="mt-8" aria-label="Demo">
-            <h2 className="text-lg font-semibold tracking-[-0.01em]">Demo</h2>
+            <h2
+              id="demo"
+              className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+            >
+              <HeadingAnchor id="demo">Demo</HeadingAnchor>
+            </h2>
             <p className="mt-2 text-[13px] text-muted-foreground">
               Drag to orbit the object, switch the dither pattern, then open the
               controls to swap in your own GLB/glTF model, SVG, or image by URL
diff --git a/src/app/(shell)/docs/components/droplets/page.tsx b/src/app/(shell)/docs/components/droplets/page.tsx
index b16c201..0081534 100644
--- a/src/app/(shell)/docs/components/droplets/page.tsx
+++ b/src/app/(shell)/docs/components/droplets/page.tsx
@@ -151,6 +151,7 @@ export default async function DropletsPage() {
         installItem="droplets"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Raindrops refract the photo beneath them as they slide down the page."
diff --git a/src/app/(shell)/docs/components/frost/page.tsx b/src/app/(shell)/docs/components/frost/page.tsx
index e079624..cccdd76 100644
--- a/src/app/(shell)/docs/components/frost/page.tsx
+++ b/src/app/(shell)/docs/components/frost/page.tsx
@@ -210,6 +210,7 @@ export default async function FrostPage() {
         installItem="frost"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Hover across the photo to melt a hole through the ice."
diff --git a/src/app/(shell)/docs/components/glass-object/page.tsx b/src/app/(shell)/docs/components/glass-object/page.tsx
index 07ea6ae..b170895 100644
--- a/src/app/(shell)/docs/components/glass-object/page.tsx
+++ b/src/app/(shell)/docs/components/glass-object/page.tsx
@@ -6,6 +6,7 @@ import type { ApiProp } from "@/components/docs/api-reference";
 import { getComponentSources } from "@/lib/registry";
 import { highlight } from "@/components/docs/highlight";
 import { GlassObjectDemo } from "@/demos/glass-object-demo";
+import { HeadingAnchor } from "@/components/docs/heading-anchor";
 
 export const metadata: Metadata = {
   title: "Glass Object",
@@ -226,9 +227,15 @@ export default async function GlassObjectPage() {
         installItem="glass-object"
         tags={["webgl", "three.js", "3D"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <section className="mt-8" aria-label="Demo">
-            <h2 className="text-lg font-semibold tracking-[-0.01em]">Demo</h2>
+            <h2
+              id="demo"
+              className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+            >
+              <HeadingAnchor id="demo">Demo</HeadingAnchor>
+            </h2>
             <p className="mt-2 text-[13px] text-muted-foreground">
               Drag to orbit the glass, then open the controls to tune the
               refraction or swap in your own model, SVG, or image by URL or from
diff --git a/src/app/(shell)/docs/components/glass/page.tsx b/src/app/(shell)/docs/components/glass/page.tsx
index cd578ca..dfb3f4a 100644
--- a/src/app/(shell)/docs/components/glass/page.tsx
+++ b/src/app/(shell)/docs/components/glass/page.tsx
@@ -147,6 +147,7 @@ export default async function GlassPage() {
         installItem="glass"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Move the lens over the photo to magnify every detail."
diff --git a/src/app/(shell)/docs/components/glitch/page.tsx b/src/app/(shell)/docs/components/glitch/page.tsx
index d3f8352..718e4bb 100644
--- a/src/app/(shell)/docs/components/glitch/page.tsx
+++ b/src/app/(shell)/docs/components/glitch/page.tsx
@@ -96,6 +96,7 @@ export default async function GlitchPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Photos make the tears and RGB splits easy to see. Drop the interval to 0 for a constant broadcast failure."
diff --git a/src/app/(shell)/docs/components/grid/page.tsx b/src/app/(shell)/docs/components/grid/page.tsx
index 630d2b4..b846471 100644
--- a/src/app/(shell)/docs/components/grid/page.tsx
+++ b/src/app/(shell)/docs/components/grid/page.tsx
@@ -155,6 +155,7 @@ export default async function GridPage() {
         installItem="grid"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Move your cursor across the photo to ripple it tile by tile."
diff --git a/src/app/(shell)/docs/components/hex-float/page.tsx b/src/app/(shell)/docs/components/hex-float/page.tsx
index 3397eef..a8ea81a 100644
--- a/src/app/(shell)/docs/components/hex-float/page.tsx
+++ b/src/app/(shell)/docs/components/hex-float/page.tsx
@@ -159,6 +159,7 @@ export default async function HexFloatPage() {
         installItem="hex-float"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Move your cursor over the photos to open a readable window and watch the ring of tiles glint."
diff --git a/src/app/(shell)/docs/components/laser/page.tsx b/src/app/(shell)/docs/components/laser/page.tsx
index 8f3e62b..63c07af 100644
--- a/src/app/(shell)/docs/components/laser/page.tsx
+++ b/src/app/(shell)/docs/components/laser/page.tsx
@@ -5,6 +5,7 @@ import { Footer } from "@/components/landing/footer";
 import type { ApiProp } from "@/components/docs/api-reference";
 import { getComponentSources } from "@/lib/registry";
 import { highlight } from "@/components/docs/highlight";
+import { HeadingAnchor } from "@/components/docs/heading-anchor";
 import { LaserDemo } from "@/demos/laser-demo";
 
 export const metadata: Metadata = {
@@ -139,6 +140,20 @@ export default async function LaserPage() {
         installItem="laser"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
+        beforeInstall={
+          <section className="mt-8" aria-label="Demo">
+            <h2
+              id="demo"
+              className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+            >
+              <HeadingAnchor id="demo">Demo</HeadingAnchor>
+            </h2>
+            <p className="mt-2 text-[13px] text-muted-foreground">
+              Scroll to see new content print in from behind the laser beam, hot and shimmering.
+            </p>
+          </section>
+        }
       />
       <div className="mx-auto mt-24 w-full max-w-3xl">
         <Footer variant="docs" />
diff --git a/src/app/(shell)/docs/components/liquid/page.tsx b/src/app/(shell)/docs/components/liquid/page.tsx
index 1252eb2..701f600 100644
--- a/src/app/(shell)/docs/components/liquid/page.tsx
+++ b/src/app/(shell)/docs/components/liquid/page.tsx
@@ -135,6 +135,7 @@ export default async function LiquidPage() {
         installItem="liquid"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Drag across the photo to stir it like liquid."
diff --git a/src/app/(shell)/docs/components/magnify/page.tsx b/src/app/(shell)/docs/components/magnify/page.tsx
index 437a4cc..dddda97 100644
--- a/src/app/(shell)/docs/components/magnify/page.tsx
+++ b/src/app/(shell)/docs/components/magnify/page.tsx
@@ -192,6 +192,7 @@ export default async function MagnifyPage() {
         installItem="magnify"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Scan the photo with the lens, then click to send a ripple through it."
diff --git a/src/app/(shell)/docs/components/particle-object/page.tsx b/src/app/(shell)/docs/components/particle-object/page.tsx
index 64aca9f..29aac87 100644
--- a/src/app/(shell)/docs/components/particle-object/page.tsx
+++ b/src/app/(shell)/docs/components/particle-object/page.tsx
@@ -5,6 +5,7 @@ import { Footer } from "@/components/landing/footer";
 import type { ApiProp } from "@/components/docs/api-reference";
 import { getComponentSources } from "@/lib/registry";
 import { highlight } from "@/components/docs/highlight";
+import { HeadingAnchor } from "@/components/docs/heading-anchor";
 import { ParticleObjectDemo } from "@/demos/particle-object-demo";
 
 export const metadata: Metadata = {
@@ -211,9 +212,15 @@ export default async function ParticleObjectPage() {
         installItem="particle-object"
         tags={["webgl", "three.js", "3D"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <section className="mt-8" aria-label="Demo">
-            <h2 className="text-lg font-semibold tracking-[-0.01em]">Demo</h2>
+            <h2
+              id="demo"
+              className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+            >
+              <HeadingAnchor id="demo">Demo</HeadingAnchor>
+            </h2>
             <p className="mt-2 text-[13px] text-muted-foreground">
               Sweep the cursor through the particles, drag to orbit, then open
               the controls to swap in your own model, SVG, or image by URL or
diff --git a/src/app/(shell)/docs/components/particle-reveal/page.tsx b/src/app/(shell)/docs/components/particle-reveal/page.tsx
index b91473a..30dbe7b 100644
--- a/src/app/(shell)/docs/components/particle-reveal/page.tsx
+++ b/src/app/(shell)/docs/components/particle-reveal/page.tsx
@@ -5,6 +5,7 @@ import { Footer } from "@/components/landing/footer";
 import type { ApiProp } from "@/components/docs/api-reference";
 import { getComponentSources } from "@/lib/registry";
 import { highlight } from "@/components/docs/highlight";
+import { HeadingAnchor } from "@/components/docs/heading-anchor";
 import { ParticleRevealDemo } from "@/demos/particle-reveal-demo";
 
 export const metadata: Metadata = {
@@ -120,7 +121,23 @@ export default async function ParticleRevealPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
-        beforeInstall={<ParticleRevealDemo />}
+        demoSection
+        beforeInstall={
+          <section className="mt-8" aria-label="Demo">
+            <h2
+              id="demo"
+              className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+            >
+              <HeadingAnchor id="demo">Demo</HeadingAnchor>
+            </h2>
+            <p className="mt-2 text-[13px] text-muted-foreground">
+              Bring the cursor close to merge the dust back into crisp, full-color UI.
+            </p>
+            <div className="mt-3">
+              <ParticleRevealDemo />
+            </div>
+          </section>
+        }
       />
       <div className="mx-auto mt-24 w-full max-w-3xl">
         <Footer variant="docs" />
diff --git a/src/app/(shell)/docs/components/particle-scroll/page.tsx b/src/app/(shell)/docs/components/particle-scroll/page.tsx
index 080aa7a..df716d6 100644
--- a/src/app/(shell)/docs/components/particle-scroll/page.tsx
+++ b/src/app/(shell)/docs/components/particle-scroll/page.tsx
@@ -128,6 +128,7 @@ export default async function ParticleScrollPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Rich imagery makes the effect shine, watch every pixel of the photo scatter into dust and settle back as it crosses the line."
diff --git a/src/app/(shell)/docs/components/peel/page.tsx b/src/app/(shell)/docs/components/peel/page.tsx
index 52802dd..bd935be 100644
--- a/src/app/(shell)/docs/components/peel/page.tsx
+++ b/src/app/(shell)/docs/components/peel/page.tsx
@@ -5,6 +5,7 @@ import { Footer } from "@/components/landing/footer";
 import type { ApiProp } from "@/components/docs/api-reference";
 import { getComponentSources } from "@/lib/registry";
 import { highlight } from "@/components/docs/highlight";
+import { HeadingAnchor } from "@/components/docs/heading-anchor";
 import { PeelDemo } from "@/demos/peel-demo";
 
 export const metadata: Metadata = {
@@ -141,7 +142,23 @@ export default async function PeelPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
-        beforeInstall={<PeelDemo />}
+        demoSection
+        beforeInstall={
+          <section className="mt-8" aria-label="Demo">
+            <h2
+              id="demo"
+              className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+            >
+              <HeadingAnchor id="demo">Demo</HeadingAnchor>
+            </h2>
+            <p className="mt-2 text-[13px] text-muted-foreground">
+              Move the cursor to an edge and watch the live page peel back like a sticker.
+            </p>
+            <div className="mt-3">
+              <PeelDemo />
+            </div>
+          </section>
+        }
       />
       <div className="mx-auto mt-24 w-full max-w-3xl">
         <Footer variant="docs" />
diff --git a/src/app/(shell)/docs/components/retro-dither/page.tsx b/src/app/(shell)/docs/components/retro-dither/page.tsx
index 8853ce7..1e0f3f9 100644
--- a/src/app/(shell)/docs/components/retro-dither/page.tsx
+++ b/src/app/(shell)/docs/components/retro-dither/page.tsx
@@ -134,6 +134,7 @@ export default async function RetroDitherPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Move your cursor over the photo to see how the dither treats images."
diff --git a/src/app/(shell)/docs/components/ripple/page.tsx b/src/app/(shell)/docs/components/ripple/page.tsx
index 623e9d4..c08e105 100644
--- a/src/app/(shell)/docs/components/ripple/page.tsx
+++ b/src/app/(shell)/docs/components/ripple/page.tsx
@@ -110,6 +110,7 @@ export default async function RipplePage() {
         installItem="ripple"
         tags={["html-in-canvas"]}
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Click the photos. Refraction and dispersion show best over imagery."
diff --git a/src/app/(shell)/docs/components/shatter/page.tsx b/src/app/(shell)/docs/components/shatter/page.tsx
index 7d2852c..d369ebe 100644
--- a/src/app/(shell)/docs/components/shatter/page.tsx
+++ b/src/app/(shell)/docs/components/shatter/page.tsx
@@ -158,6 +158,7 @@ export default async function ShatterPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Move your cursor over the photo to break it into floating glass shards."
diff --git a/src/app/(shell)/docs/components/vhs/page.tsx b/src/app/(shell)/docs/components/vhs/page.tsx
index 32280f2..6582880 100644
--- a/src/app/(shell)/docs/components/vhs/page.tsx
+++ b/src/app/(shell)/docs/components/vhs/page.tsx
@@ -141,6 +141,7 @@ export default async function VHSPage() {
         tags={["html-in-canvas"]}
         requiresHtmlInCanvas
         apiReference={API_REFERENCE}
+        demoSection
         beforeInstall={
           <DemoImageSection
             hint="Photos show the tape playback treatment best, wave, chroma bleed, and grain included."
diff --git a/src/app/(shell)/layout.tsx b/src/app/(shell)/layout.tsx
index 0661ec5..413cc44 100644
--- a/src/app/(shell)/layout.tsx
+++ b/src/app/(shell)/layout.tsx
@@ -6,6 +6,7 @@ import { DocsMobileNav } from "@/components/docs/docs-mobile-nav";
 import { GitHubStars } from "@/components/common/github-stars";
 import { SearchButton, SearchDialog } from "@/components/common/site-search";
 import { ThemeToggle } from "@/components/common/theme-toggle";
+import { TOCLayout } from "@/components/docs/toc-layout";
 
 export default function ShellLayout({
   children,
@@ -41,9 +42,7 @@ export default function ShellLayout({
 
       <SearchDialog />
 
-      <main className="flex-1 px-5 py-10 sm:px-8 lg:pt-16 lg:pr-8 lg:pl-72">
-        {children}
-      </main>
+      <TOCLayout>{children}</TOCLayout>
     </div>
   );
 }
diff --git a/src/components/docs/component-doc.tsx b/src/components/docs/component-doc.tsx
index 216209e..3ace7c8 100644
--- a/src/components/docs/component-doc.tsx
+++ b/src/components/docs/component-doc.tsx
@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import Link from "next/link";
-import { ChevronRight } from "lucide-react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
 
 import { HtmlInCanvasBanner } from "@/components/common/html-in-canvas-banner";
 import { ApiReference, type ApiProp } from "@/components/docs/api-reference";
@@ -8,8 +8,12 @@ import { CodeTabs, type CodeVariant } from "@/components/docs/code-tabs";
 import { CopyMenu } from "@/components/docs/copy-menu";
 import { DependencyTabs } from "@/components/docs/dependency-tabs";
 import { InstallTabs } from "@/components/docs/install-tabs";
+import type { TOCItemType } from "@/components/docs/toc-minimap";
+import { TOCSetter } from "@/components/docs/toc-layout";
+import { HeadingAnchor } from "@/components/docs/heading-anchor";
 import { getComponentDependencies, getDemoSource } from "@/lib/registry";
 import { COMPONENTS } from "@/data/components";
+import { TOCMobile } from "./toc-mobile";
 
 export interface ComponentDocProps {
   title: string;
@@ -32,6 +36,11 @@ export interface ComponentDocProps {
   requiresHtmlInCanvas?: boolean;
   /** Props table shown in the API reference section. */
   apiReference?: ApiProp[];
+  /**
+   * Add a "Demo" entry at the top of the auto-generated TOC minimap.
+   * Set true when beforeInstall contains a section with id="demo".
+   */
+  demoSection?: boolean;
 }
 
 export function ComponentDoc({
@@ -43,121 +52,144 @@ export function ComponentDoc({
   installItem,
   tags,
   apiReference,
+  demoSection = false,
   requiresHtmlInCanvas = false,
 }: ComponentDocProps) {
   const { dependencies, devDependencies } =
     getComponentDependencies(installItem);
   const demoSource = getDemoSource(installItem);
 
+  const hasDependencies = dependencies.length > 0 || devDependencies.length > 0;
+  const hasApiReference = !!apiReference && apiReference.length > 0;
+  const toc: TOCItemType[] = [
+    ...(demoSection ? [{ title: "Demo", url: "#demo", depth: 2 }] : []),
+    { title: "Install", url: "#install", depth: 2 },
+    ...(hasDependencies
+      ? [{ title: "Dependencies", url: "#dependencies", depth: 2 }]
+      : []),
+    { title: "Code", url: "#code", depth: 2 },
+    ...(hasApiReference
+      ? [{ title: "API reference", url: "#api-reference", depth: 2 }]
+      : []),
+  ];
+
   return (
-    <article className="mx-auto w-full max-w-3xl">
-      <div className="flex items-start justify-between gap-4">
-        <div>
-          <h1 className="text-3xl font-semibold tracking-[-0.02em]">{title}</h1>
-          <p className="mt-3 max-w-xl text-base leading-7 text-muted-foreground">
-            {description}
-          </p>
-          {tags && tags.length > 0 ? (
-            <div className="mt-4 flex flex-wrap gap-1.5">
-              {tags.map((tag) => (
-                <span
-                  key={tag}
-                  className="rounded-full border border-border/60 px-2.5 py-0.5 text-[11.5px] text-muted-foreground"
-                >
-                  {tag}
-                </span>
-              ))}
-            </div>
-          ) : null}
-        </div>
-        <CopyMenu
-          title={title}
-          description={description}
-          installItem={installItem}
-          variants={variants}
-          apiReference={apiReference}
-          dependencies={dependencies}
-          devDependencies={devDependencies}
-          demoSource={demoSource}
-        />
-      </div>
-
-      {requiresHtmlInCanvas ? <HtmlInCanvasBanner /> : null}
-
-      {preview ? (
-        <section className="mt-8" aria-label="Preview">
-          <div className="relative h-105 touch-none overflow-hidden rounded-xl border border-border/60 bg-background">
-            {preview}
+    <>
+      <article className="mx-auto w-full max-w-3xl">
+        <div className="flex items-start justify-between gap-4">
+          <div>
+            <h1 className="text-3xl font-semibold tracking-[-0.02em]">
+              {title}
+            </h1>
+            <p className="mt-3 max-w-xl text-base leading-7 text-muted-foreground">
+              {description}
+            </p>
+            {tags && tags.length > 0 ? (
+              <div className="mt-4 flex flex-wrap gap-1.5">
+                {tags.map((tag) => (
+                  <span
+                    key={tag}
+                    className="rounded-full border border-border/60 px-2.5 py-0.5 text-[11.5px] text-muted-foreground"
+                  >
+                    {tag}
+                  </span>
+                ))}
+              </div>
+            ) : null}
           </div>
-        </section>
-      ) : null}
+          <CopyMenu
+            title={title}
+            description={description}
+            installItem={installItem}
+            variants={variants}
+            apiReference={apiReference}
+            dependencies={dependencies}
+            devDependencies={devDependencies}
+            demoSource={demoSource}
+          />
+        </div>
 
-      {beforeInstall}
+        {requiresHtmlInCanvas ? <HtmlInCanvasBanner /> : null}
 
-      <section className="mt-8" aria-label="Installation">
-        <h2
-          id="install"
-          className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
-        >
-          Install
-        </h2>
-        <div className="mt-3">
-          <InstallTabs item={installItem} />
-        </div>
-        <p className="mt-2 text-[13px] text-muted-foreground">
-          Or copy the source below into your project.
-        </p>
-      </section>
+        <TOCMobile items={toc} />
 
-      {dependencies.length > 0 || devDependencies.length > 0 ? (
-        <section className="mt-8" aria-label="Dependencies">
+        {preview ? (
+          <section className="mt-8" aria-label="Preview">
+            <div className="relative h-105 touch-none overflow-hidden rounded-xl border border-border/60 bg-background">
+              {preview}
+            </div>
+          </section>
+        ) : null}
+
+        {beforeInstall}
+
+        <section className="mt-8" aria-label="Installation">
           <h2
-            id="dependencies"
+            id="install"
             className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
           >
-            Dependencies
+            <HeadingAnchor id="install">Install</HeadingAnchor>
           </h2>
-          <p className="mt-2 text-[13px] text-muted-foreground">
-            The install command above adds these automatically. If you copy the
-            source by hand, install them yourself.
-          </p>
           <div className="mt-3">
-            <DependencyTabs
-              dependencies={dependencies}
-              devDependencies={devDependencies}
-            />
+            <InstallTabs item={installItem} />
           </div>
+          <p className="mt-2 text-[13px] text-muted-foreground">
+            Or copy the source below into your project.
+          </p>
         </section>
-      ) : null}
 
-      <section className="mt-8" aria-label="Code">
-        <h2
-          id="code"
-          className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
-        >
-          Code
-        </h2>
-        <div className="mt-3">
-          <CodeTabs variants={variants} />
-        </div>
-      </section>
+        {dependencies.length > 0 || devDependencies.length > 0 ? (
+          <section className="mt-8" aria-label="Dependencies">
+            <h2
+              id="dependencies"
+              className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+            >
+              <HeadingAnchor id="dependencies">Dependencies</HeadingAnchor>
+            </h2>
+            <p className="mt-2 text-[13px] text-muted-foreground">
+              The install command above adds these automatically. If you copy
+              the source by hand, install them yourself.
+            </p>
+            <div className="mt-3">
+              <DependencyTabs
+                dependencies={dependencies}
+                devDependencies={devDependencies}
+              />
+            </div>
+          </section>
+        ) : null}
 
-      {apiReference && apiReference.length > 0 ? (
-        <section className="mt-8" aria-label="API reference">
+        <section className="mt-8" aria-label="Code">
           <h2
-            id="api-reference"
+            id="code"
             className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
           >
-            API reference
+            <HeadingAnchor id="code">Code</HeadingAnchor>
           </h2>
           <div className="mt-3">
-            <ApiReference props={apiReference} />
+            <CodeTabs variants={variants} />
           </div>
         </section>
-      ) : null}
 
-      <ComponentPager slug={installItem} />
-    </article>
+        {apiReference && apiReference.length > 0 ? (
+          <section className="mt-8" aria-label="API reference">
+            <h2
+              id="api-reference"
+              className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+            >
+              <HeadingAnchor id="api-reference">API reference</HeadingAnchor>
+            </h2>
+            <div className="mt-3">
+              <ApiReference props={apiReference} />
+            </div>
+          </section>
+        ) : null}
+
+        <ComponentPager slug={installItem} />
+      </article>
+
+      <TOCSetter items={toc} />
+    </>
   );
 }
 
@@ -180,12 +212,12 @@ function ComponentPager({ slug }: { slug: string }) {
           rel="prev"
           className="group min-w-0 rounded-xl border border-border/60 p-4 transition-colors duration-150 hover:bg-muted/40"
         >
-          <span className="flex items-center justify-between gap-2 text-sm font-medium text-foreground">
-            {prev.name}
-            <ChevronRight
+          <span className="flex items-center gap-2 text-sm font-medium text-foreground">
+            <ChevronLeft
               aria-hidden
-              className="size-4 shrink-0 text-muted-foreground transition-transform duration-200 ease-out group-hover:translate-x-0.5"
+              className="-mx-1 size-4 shrink-0 text-muted-foreground transition-transform duration-200 ease-out group-hover:-translate-x-0.5"
             />
+            {prev.name}
           </span>
           <span className="mt-1 block truncate text-[13px] text-muted-foreground">
             {prev.description}
@@ -198,11 +230,11 @@ function ComponentPager({ slug }: { slug: string }) {
           rel="next"
           className="group min-w-0 rounded-xl border border-border/60 p-4 transition-colors duration-150 hover:bg-muted/40 sm:col-start-2"
         >
-          <span className="flex items-center justify-between gap-2 text-sm font-medium text-foreground">
+          <span className="flex items-center justify-end gap-2 text-sm font-medium text-foreground">
             {next.name}
             <ChevronRight
               aria-hidden
-              className="size-4 shrink-0 text-muted-foreground transition-transform duration-200 ease-out group-hover:translate-x-0.5"
+              className="-mx-1 size-4 shrink-0 text-muted-foreground transition-transform duration-200 ease-out group-hover:translate-x-0.5"
             />
           </span>
           <span className="mt-1 block truncate text-[13px] text-muted-foreground">
diff --git a/src/components/docs/copy-button.tsx b/src/components/docs/copy-button.tsx
index 6e202ee..a9a49b9 100644
--- a/src/components/docs/copy-button.tsx
+++ b/src/components/docs/copy-button.tsx
@@ -40,18 +40,18 @@ export function CopyButton({
         className,
       )}
     >
-      <span className="grid size-[15px]">
+      <span className="grid size-3.75">
         <Copy
           aria-hidden
           className={cn(
-            "col-start-1 row-start-1 size-[15px] transition-[opacity,filter] duration-200 ease-out motion-reduce:transition-none",
+            "col-start-1 row-start-1 size-3.75 transition-[opacity,filter] duration-200 ease-out motion-reduce:transition-none",
             copied ? "opacity-0 blur-[3px]" : "opacity-100 blur-none",
           )}
         />
         <Check
           aria-hidden
           className={cn(
-            "col-start-1 row-start-1 size-[15px] transition-[opacity,filter] duration-200 ease-out motion-reduce:transition-none",
+            "col-start-1 row-start-1 size-3.75 transition-[opacity,filter] duration-200 ease-out motion-reduce:transition-none",
             copied ? "opacity-100 blur-none" : "opacity-0 blur-[3px]",
           )}
         />
diff --git a/src/components/docs/heading-anchor.tsx b/src/components/docs/heading-anchor.tsx
new file mode 100644
index 0000000..f42131f
--- /dev/null
+++ b/src/components/docs/heading-anchor.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { Check, Link } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+interface HeadingAnchorProps {
+  id: string;
+  children: React.ReactNode;
+}
+
+export function HeadingAnchor({ id, children }: HeadingAnchorProps) {
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    };
+  }, []);
+
+  const handleCopy = async () => {
+    const url = `${window.location.origin}${window.location.pathname}#${id}`;
+    await navigator.clipboard.writeText(url);
+    setCopied(true);
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    timeoutRef.current = setTimeout(() => setCopied(false), 1600);
+  };
+
+  return (
+    <span className="group/anchor inline-flex items-center gap-2">
+      <a href={`#${id}`} className="text-foreground no-underline">
+        {children}
+      </a>
+      <button
+        type="button"
+        onClick={handleCopy}
+        aria-label={copied ? "Copied" : `Copy link to ${id} section`}
+        className={cn(
+          "opacity-0 transition-[color,opacity,transform] duration-150 ease-out cursor-pointer",
+          "group-hover/anchor:opacity-100",
+          "text-muted-foreground hover:text-foreground active:scale-95",
+          "motion-reduce:transition-none",
+        )}
+      >
+        <span className="grid size-3.75">
+          <Link
+            aria-hidden
+            className={cn(
+              "col-start-1 row-start-1 size-3.75 transition-[opacity,filter] duration-200 ease-out motion-reduce:transition-none",
+              copied ? "opacity-0 blur-[3px]" : "opacity-100 blur-none",
+            )}
+          />
+          <Check
+            aria-hidden
+            className={cn(
+              "col-start-1 row-start-1 size-3.75 transition-[opacity,filter] duration-200 ease-out motion-reduce:transition-none",
+              copied ? "opacity-100 blur-none" : "opacity-0 blur-[3px]",
+            )}
+          />
+        </span>
+      </button>
+    </span>
+  );
+}
diff --git a/src/components/docs/toc-layout.tsx b/src/components/docs/toc-layout.tsx
new file mode 100644
index 0000000..10d46b9
--- /dev/null
+++ b/src/components/docs/toc-layout.tsx
@@ -0,0 +1,56 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+
+import { TOCMinimap, type TOCItemType } from "./toc-minimap";
+
+interface TOCContextValue {
+  items: TOCItemType[];
+  setItems: (items: TOCItemType[]) => void;
+}
+
+const TOCContext = createContext<TOCContextValue>({
+  items: [],
+  setItems: () => {},
+});
+
+export function useTOC() {
+  return useContext(TOCContext);
+}
+
+export function TOCLayout({ children }: { children: ReactNode }) {
+  const [items, setItems] = useState<TOCItemType[]>([]);
+
+  const contextValue = useMemo(() => ({ items, setItems }), [items, setItems]);
+
+  return (
+    <TOCContext.Provider value={contextValue}>
+      <main className="flex-1 px-5 py-10 sm:px-8 lg:pt-16 lg:pr-8 lg:pl-72">
+        {children}
+      </main>
+      {items.length > 0 && (
+        <aside className="fixed right-[calc(1rem+var(--demo-sbw,0px))] top-50 z-50 hidden xl:block">
+          <TOCMinimap items={items} />
+        </aside>
+      )}
+    </TOCContext.Provider>
+  );
+}
+
+export function TOCSetter({ items }: { items: TOCItemType[] }) {
+  const { setItems } = useTOC();
+
+  useEffect(() => {
+    setItems(items);
+    return () => setItems([]);
+  }, [items, setItems]);
+
+  return null;
+}
diff --git a/src/components/docs/toc-minimap.tsx b/src/components/docs/toc-minimap.tsx
new file mode 100644
index 0000000..ccc1d46
--- /dev/null
+++ b/src/components/docs/toc-minimap.tsx
@@ -0,0 +1,165 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { cn } from "@/lib/utils";
+import {
+  HoverCard,
+  HoverCardContent,
+  HoverCardTrigger,
+} from "@/components/ui/hover-card";
+
+export type TOCItemType = {
+  title: React.ReactNode;
+  url: string;
+  depth: number;
+};
+
+export type TOCMinimapProps = {
+  items: TOCItemType[];
+  className?: string;
+};
+
+export function TOCMinimap({ items, className }: TOCMinimapProps) {
+  const [open, setOpen] = useState(false);
+  const closeTimer = useRef<number | undefined>(undefined);
+  const itemIds = useMemo(
+    () => items.map((item) => item.url.replace("#", "")),
+    [items],
+  );
+
+  const activeHeading = useActiveHeading(itemIds);
+
+  const close = useCallback(() => {
+    clearTimeout(closeTimer.current);
+    closeTimer.current = window.setTimeout(() => setOpen(false), 150);
+  }, []);
+
+  const cancelClose = useCallback(() => {
+    clearTimeout(closeTimer.current);
+    setOpen(true);
+  }, []);
+
+  useEffect(() => {
+    return () => clearTimeout(closeTimer.current);
+  }, []);
+
+  if (!items.length) {
+    return null;
+  }
+
+  function handleItemClick(url: string) {
+    scrollToHeading(url);
+  }
+
+  return (
+    <div
+      className={cn("ml-auto w-18", className)}
+      onPointerEnter={cancelClose}
+      onPointerLeave={close}
+    >
+      <HoverCard
+        open={open}
+        onOpenChange={(nextOpen) => {
+          if (nextOpen) setOpen(true);
+        }}
+      >
+        <HoverCardTrigger
+          delay={0}
+          closeDelay={0}
+          render={
+            <div className="flex max-h-[50dvh] flex-col gap-3 overflow-hidden py-3 pl-6 opacity-100 transition-opacity duration-200 data-popup-open:opacity-0">
+              {items.map((item) => (
+                <div
+                  key={item.url}
+                  data-depth={item.depth}
+                  data-active={item.url === `#${activeHeading}`}
+                  className={cn(
+                    "h-0.5 w-6 shrink-0 rounded-xs bg-ring/50 transition-[background-color] duration-200",
+                    "data-[depth=3]:ml-2 data-[depth=3]:w-4",
+                    "data-[depth=4]:ml-4 data-[depth=4]:w-2",
+                    "data-active:bg-foreground",
+                  )}
+                />
+              ))}
+            </div>
+          }
+        />
+
+        <HoverCardContent
+          className="w-56 overflow-hidden p-0 duration-200 data-[side=left]:slide-in-from-right-3 data-[side=left]:slide-out-to-right-3 data-open:zoom-in-100 data-closed:zoom-out-100"
+          align="start"
+          alignOffset={0}
+          positionMethod="fixed"
+          side="left"
+          sideOffset={-60}
+          onPointerEnter={cancelClose}
+          onPointerLeave={close}
+        >
+          <div className="flex max-h-[50dvh] overflow-y-auto overscroll-contain">
+            <ul className="flex size-full flex-col px-6 py-4 text-sm">
+              {items.map((item) => (
+                <li key={item.url} className="flex py-1">
+                  <button
+                    data-depth={item.depth}
+                    data-active={item.url === `#${activeHeading}`}
+                    className={cn(
+                      "w-full text-left transition-[color] duration-200 cursor-pointer!",
+                      "text-muted-foreground hover:text-foreground data-active:text-foreground",
+                      "data-[depth=3]:pl-4 data-[depth=4]:pl-8",
+                    )}
+                    onClick={() => handleItemClick(item.url)}
+                  >
+                    {item.title}
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </div>
+        </HoverCardContent>
+      </HoverCard>
+    </div>
+  );
+}
+
+export function useActiveHeading(itemIds: string[]) {
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+          }
+        }
+      },
+      { rootMargin: "0% 0% -80% 0%", threshold: 0.98 },
+    );
+
+    for (const id of itemIds ?? []) {
+      const element = document.getElementById(id);
+      if (element) {
+        observer.observe(element);
+      }
+    }
+
+    return () => {
+      for (const id of itemIds ?? []) {
+        const element = document.getElementById(id);
+        if (element) {
+          observer.unobserve(element);
+        }
+      }
+    };
+  }, [itemIds]);
+
+  return activeId ?? itemIds[0] ?? null;
+}
+
+function scrollToHeading(url: string) {
+  history.pushState(null, "", url);
+  document.getElementById(url.replace("#", ""))?.scrollIntoView({
+    behavior: "smooth",
+  });
+}
diff --git a/src/components/docs/toc-mobile.tsx b/src/components/docs/toc-mobile.tsx
new file mode 100644
index 0000000..a7b30ae
--- /dev/null
+++ b/src/components/docs/toc-mobile.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {
+  Accordion,
+  AccordionHeader,
+  AccordionItem,
+  AccordionPanel,
+  AccordionTrigger,
+} from "@/components/ui/accordion";
+import { cn } from "@/lib/utils";
+import type { TOCItemType } from "./toc-minimap";
+
+export function TOCMobile({ items }: { items: TOCItemType[] }) {
+  if (!items.length) return null;
+
+  function scrollToHeading(url: string) {
+    history.pushState(null, "", url);
+    document.getElementById(url.replace("#", ""))?.scrollIntoView({
+      behavior: "smooth",
+    });
+  }
+
+  return (
+    <Accordion className="xl:hidden not-typeset mt-6 mb-4 rounded-xl border border-border/60 bg-muted/30 px-4 py-3">
+      <AccordionItem value="toc">
+        <AccordionHeader render={<div />} className="flex">
+          <AccordionTrigger className="w-full text-sm font-medium">
+            On this page
+          </AccordionTrigger>
+        </AccordionHeader>
+        <AccordionPanel>
+          <nav className="mt-2 flex flex-col gap-0.5">
+            {items.map((item) => (
+              <button
+                key={item.url}
+                onClick={() => scrollToHeading(item.url)}
+                className={cn(
+                  "w-full text-left text-[13px] leading-6 text-muted-foreground transition-colors hover:text-foreground py-1",
+                  item.depth >= 3 && "pl-4",
+                  item.depth >= 4 && "pl-8",
+                )}
+              >
+                {item.title}
+              </button>
+            ))}
+          </nav>
+        </AccordionPanel>
+      </AccordionItem>
+    </Accordion>
+  );
+}
diff --git a/src/components/ui/hover-card.tsx b/src/components/ui/hover-card.tsx
new file mode 100644
index 0000000..141acc7
--- /dev/null
+++ b/src/components/ui/hover-card.tsx
@@ -0,0 +1,53 @@
+"use client"
+
+import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card"
+
+import { cn } from "@/lib/utils"
+
+function HoverCard({ ...props }: PreviewCardPrimitive.Root.Props) {
+  return <PreviewCardPrimitive.Root data-slot="hover-card" {...props} />
+}
+
+function HoverCardTrigger({ ...props }: PreviewCardPrimitive.Trigger.Props) {
+  return (
+    <PreviewCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+  )
+}
+
+function HoverCardContent({
+  className,
+  positionMethod = "absolute",
+  side = "bottom",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 4,
+  ...props
+}: PreviewCardPrimitive.Popup.Props &
+  Pick<
+    PreviewCardPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "positionMethod" | "side" | "sideOffset"
+  >) {
+  return (
+    <PreviewCardPrimitive.Portal data-slot="hover-card-portal">
+      <PreviewCardPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        positionMethod={positionMethod}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <PreviewCardPrimitive.Popup
+          data-slot="hover-card-content"
+          className={cn(
+            "z-50 w-64 origin-(--transform-origin) rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className
+          )}
+          {...props}
+        />
+      </PreviewCardPrimitive.Positioner>
+    </PreviewCardPrimitive.Portal>
+  )
+}
+
+export { HoverCard, HoverCardTrigger, HoverCardContent }
diff --git a/src/demos/demo-image-cycler.tsx b/src/demos/demo-image-cycler.tsx
index faf74f0..a663062 100644
--- a/src/demos/demo-image-cycler.tsx
+++ b/src/demos/demo-image-cycler.tsx
@@ -3,6 +3,8 @@
 import { useEffect, useState } from "react";
 import { useReducedMotion } from "motion/react";
 
+import { HeadingAnchor } from "@/components/docs/heading-anchor";
+
 const EASE = "cubic-bezier(0.23, 1, 0.32, 1)";
 
 
@@ -25,8 +27,13 @@ export function DemoImageSection({
   images?: string[];
 }) {
   return (
-    <section className="mt-8" aria-label="Demo image">
-      <h2 className="text-lg font-semibold tracking-[-0.01em]">Demo image</h2>
+    <section className="mt-8" aria-label="Demo">
+      <h2
+        id="demo"
+        className="scroll-mt-24 text-lg font-semibold tracking-[-0.01em]"
+      >
+        <HeadingAnchor id="demo">Demo</HeadingAnchor>
+      </h2>
       <p className="mt-2 text-[13px] text-muted-foreground">{hint}</p>
       <div className="mt-3 overflow-hidden rounded-xl border border-border/60">
         <DemoImageCycler images={images} alt={alt} />