prev-cli 0.9.1 → 0.11.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
-import path5 from "path";
+import path7 from "path";
 
 // src/vite/start.ts
 import { createServer as createServer2, build, preview } from "vite";
@@ -13,9 +13,9 @@ import react from "@vitejs/plugin-react-swc";
 import mdx from "@mdx-js/rollup";
 import remarkGfm from "remark-gfm";
 import rehypeHighlight from "rehype-highlight";
-import path4 from "path";
+import path6 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
 
 // src/utils/cache.ts
 import { createHash } from "crypto";
@@ -324,10 +324,15 @@ function entryPlugin(rootDir) {
       if (command === "build" && rootDir) {
         tempHtmlPath = path3.join(rootDir, "index.html");
         writeFileSync(tempHtmlPath, getHtml(entryPath, true));
+        const existingInput = config.build?.rollupOptions?.input || {};
+        const inputObj = typeof existingInput === "string" ? { _original: existingInput } : Array.isArray(existingInput) ? Object.fromEntries(existingInput.map((f, i) => [`entry${i}`, f])) : existingInput;
         return {
           build: {
             rollupOptions: {
-              input: tempHtmlPath
+              input: {
+                ...inputObj,
+                main: tempHtmlPath
+              }
             }
           }
         };
@@ -362,6 +367,73 @@ function entryPlugin(rootDir) {
   };
 }
 
+// src/vite/previews.ts
+import fg2 from "fast-glob";
+import path4 from "path";
+import { existsSync as existsSync2 } from "fs";
+async function scanPreviews(rootDir) {
+  const previewsDir = path4.join(rootDir, "previews");
+  if (!existsSync2(previewsDir)) {
+    return [];
+  }
+  const htmlFiles = await fg2.glob("**/index.html", {
+    cwd: previewsDir,
+    ignore: ["node_modules/**"]
+  });
+  return htmlFiles.map((file) => {
+    const dir = path4.dirname(file);
+    const name = dir === "." ? path4.basename(path4.dirname(path4.join(previewsDir, file))) : dir;
+    return {
+      name,
+      route: `/_preview/${name}`,
+      htmlPath: path4.join(previewsDir, file)
+    };
+  });
+}
+
+// src/vite/plugins/previews-plugin.ts
+import { existsSync as existsSync3, renameSync, mkdirSync, rmSync } from "fs";
+import path5 from "path";
+var VIRTUAL_MODULE_ID2 = "virtual:prev-previews";
+var RESOLVED_VIRTUAL_MODULE_ID2 = "\x00" + VIRTUAL_MODULE_ID2;
+function previewsPlugin(rootDir) {
+  return {
+    name: "prev-previews",
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID2) {
+        return RESOLVED_VIRTUAL_MODULE_ID2;
+      }
+    },
+    async load(id) {
+      if (id === RESOLVED_VIRTUAL_MODULE_ID2) {
+        const previews = await scanPreviews(rootDir);
+        return `export const previews = ${JSON.stringify(previews)};`;
+      }
+    },
+    handleHotUpdate({ file, server }) {
+      if (file.includes("/previews/") && file.endsWith(".html")) {
+        const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID2);
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+          return [mod];
+        }
+      }
+    },
+    closeBundle() {
+      const distDir = path5.join(rootDir, "dist");
+      const previewsDir = path5.join(distDir, "previews");
+      const targetDir = path5.join(distDir, "_preview");
+      if (existsSync3(previewsDir)) {
+        mkdirSync(path5.dirname(targetDir), { recursive: true });
+        if (existsSync3(targetDir)) {
+          rmSync(targetDir, { recursive: true });
+        }
+        renameSync(previewsDir, targetDir);
+      }
+    }
+  };
+}
+
 // src/vite/config.ts
 function createFriendlyLogger() {
   const logger = createLogger("info", { allowClearScreen: false });
@@ -417,10 +489,10 @@ function createFriendlyLogger() {
   };
 }
 function findCliRoot2() {
-  let dir = path4.dirname(fileURLToPath2(import.meta.url));
+  let dir = path6.dirname(fileURLToPath2(import.meta.url));
   for (let i = 0;i < 10; i++) {
-    const pkgPath = path4.join(dir, "package.json");
-    if (existsSync2(pkgPath)) {
+    const pkgPath = path6.join(dir, "package.json");
+    if (existsSync4(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
         if (pkg.name === "prev-cli") {
@@ -428,24 +500,24 @@ function findCliRoot2() {
         }
       } catch {}
     }
-    const parent = path4.dirname(dir);
+    const parent = path6.dirname(dir);
     if (parent === dir)
       break;
     dir = parent;
   }
-  return path4.dirname(path4.dirname(fileURLToPath2(import.meta.url)));
+  return path6.dirname(path6.dirname(fileURLToPath2(import.meta.url)));
 }
 function findNodeModules(cliRoot2) {
-  const localNodeModules = path4.join(cliRoot2, "node_modules");
-  if (existsSync2(path4.join(localNodeModules, "react"))) {
+  const localNodeModules = path6.join(cliRoot2, "node_modules");
+  if (existsSync4(path6.join(localNodeModules, "react"))) {
     return localNodeModules;
   }
   let dir = cliRoot2;
   for (let i = 0;i < 10; i++) {
-    const parent = path4.dirname(dir);
+    const parent = path6.dirname(dir);
     if (parent === dir)
       break;
-    if (path4.basename(parent) === "node_modules" && existsSync2(path4.join(parent, "react"))) {
+    if (path6.basename(parent) === "node_modules" && existsSync4(path6.join(parent, "react"))) {
       return parent;
     }
     dir = parent;
@@ -454,10 +526,12 @@ function findNodeModules(cliRoot2) {
 }
 var cliRoot2 = findCliRoot2();
 var cliNodeModules = findNodeModules(cliRoot2);
-var srcRoot2 = path4.join(cliRoot2, "src");
+var srcRoot2 = path6.join(cliRoot2, "src");
 async function createViteConfig(options) {
   const { rootDir, mode, port, include } = options;
   const cacheDir = await ensureCacheDir(rootDir);
+  const previews = await scanPreviews(rootDir);
+  const previewInputs = Object.fromEntries(previews.map((p) => [`_preview/${p.name}`, p.htmlPath]));
   return {
     root: rootDir,
     mode,
@@ -471,18 +545,46 @@ async function createViteConfig(options) {
       }),
       react(),
       pagesPlugin(rootDir, { include }),
-      entryPlugin(rootDir)
+      entryPlugin(rootDir),
+      previewsPlugin(rootDir),
+      {
+        name: "prev-preview-server",
+        configureServer(server) {
+          server.middlewares.use(async (req, res, next) => {
+            if (req.url?.startsWith("/_preview/")) {
+              const previewName = decodeURIComponent(req.url.slice("/_preview/".length).split("?")[0]);
+              const previewsDir = path6.join(rootDir, "previews");
+              const htmlPath = path6.resolve(previewsDir, previewName, "index.html");
+              if (!htmlPath.startsWith(previewsDir)) {
+                return next();
+              }
+              if (existsSync4(htmlPath)) {
+                try {
+                  const html = await server.transformIndexHtml(req.url, readFileSync2(htmlPath, "utf-8"));
+                  res.setHeader("Content-Type", "text/html");
+                  res.end(html);
+                  return;
+                } catch (err) {
+                  console.error("Error serving preview:", err);
+                  return next();
+                }
+              }
+            }
+            next();
+          });
+        }
+      }
     ],
     resolve: {
       alias: {
-        "@prev/ui": path4.join(srcRoot2, "ui"),
-        "@prev/theme": path4.join(srcRoot2, "theme"),
-        react: path4.join(cliNodeModules, "react"),
-        "react-dom": path4.join(cliNodeModules, "react-dom"),
-        "@tanstack/react-router": path4.join(cliNodeModules, "@tanstack/react-router"),
-        mermaid: path4.join(cliNodeModules, "mermaid"),
-        dayjs: path4.join(cliNodeModules, "dayjs"),
-        "@terrastruct/d2": path4.join(cliNodeModules, "@terrastruct/d2")
+        "@prev/ui": path6.join(srcRoot2, "ui"),
+        "@prev/theme": path6.join(srcRoot2, "theme"),
+        react: path6.join(cliNodeModules, "react"),
+        "react-dom": path6.join(cliNodeModules, "react-dom"),
+        "@tanstack/react-router": path6.join(cliNodeModules, "@tanstack/react-router"),
+        mermaid: path6.join(cliNodeModules, "mermaid"),
+        dayjs: path6.join(cliNodeModules, "dayjs"),
+        "@terrastruct/d2": path6.join(cliNodeModules, "@terrastruct/d2")
       },
       dedupe: [
         "react",
@@ -515,8 +617,8 @@ async function createViteConfig(options) {
       },
       warmup: {
         clientFiles: [
-          path4.join(srcRoot2, "theme/entry.tsx"),
-          path4.join(srcRoot2, "theme/styles.css")
+          path6.join(srcRoot2, "theme/entry.tsx"),
+          path6.join(srcRoot2, "theme/styles.css")
         ]
       }
     },
@@ -525,9 +627,15 @@ async function createViteConfig(options) {
       strictPort: false
     },
     build: {
-      outDir: path4.join(rootDir, "dist"),
+      outDir: path6.join(rootDir, "dist"),
       reportCompressedSize: false,
-      chunkSizeWarningLimit: 1e4
+      chunkSizeWarningLimit: 1e4,
+      rollupOptions: {
+        input: {
+          main: path6.join(srcRoot2, "theme/index.html"),
+          ...previewInputs
+        }
+      }
     }
   };
 }
@@ -641,7 +749,7 @@ var { values, positionals } = parseArgs({
   allowPositionals: true
 });
 var command = positionals[0] || "dev";
-var rootDir = path5.resolve(values.cwd || positionals[1] || ".");
+var rootDir = path7.resolve(values.cwd || positionals[1] || ".");
 function printHelp() {
   console.log(`
 prev - Zero-config documentation site generator

package/dist/vite/plugins/previews-plugin.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function previewsPlugin(rootDir: string): Plugin;

package/dist/vite/previews.d.ts

@@ -0,0 +1,6 @@
+export interface Preview {
+    name: string;
+    route: string;
+    htmlPath: string;
+}
+export declare function scanPreviews(rootDir: string): Promise<Preview[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prev-cli",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Transform MDX directories into beautiful documentation websites",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,7 @@
     "test:all": "bun run test && bun run test:integration"
   },
   "dependencies": {
+    "@mdx-js/react": "^3.1.1",
     "@mdx-js/rollup": "^3.0.0",
     "@tailwindcss/vite": "^4.0.0",
     "@tanstack/react-router": "^1.145.7",

package/src/theme/Preview.tsx

@@ -0,0 +1,382 @@
+import React, { useState, useEffect, useRef, useCallback } from 'react'
+import { Smartphone, Tablet, Monitor, SunMedium, Moon, Maximize2, Minimize2, GripVertical, SlidersHorizontal, X } from 'lucide-react'
+
+interface PreviewProps {
+  src: string
+  height?: string | number
+  title?: string
+}
+
+type DeviceMode = 'mobile' | 'tablet' | 'desktop'
+
+const DEVICE_WIDTHS: Record<DeviceMode, number | '100%'> = {
+  mobile: 375,
+  tablet: 768,
+  desktop: '100%',
+}
+
+interface Position {
+  x: number
+  y: number
+}
+
+export function Preview({ src, height = 400, title }: PreviewProps) {
+  const [isFullscreen, setIsFullscreen] = useState(false)
+  const [deviceMode, setDeviceMode] = useState<DeviceMode>('desktop')
+  const [customWidth, setCustomWidth] = useState<number | null>(null)
+  const [isDarkMode, setIsDarkMode] = useState(false)
+  const [showSlider, setShowSlider] = useState(false)
+  const [pillPosition, setPillPosition] = useState<Position>({ x: 0, y: 0 })
+  const [isDragging, setIsDragging] = useState(false)
+  const [dragOffset, setDragOffset] = useState<Position>({ x: 0, y: 0 })
+
+  const iframeRef = useRef<HTMLIFrameElement>(null)
+  const pillRef = useRef<HTMLDivElement>(null)
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const previewUrl = `/_preview/${src}`
+  const displayTitle = title || src
+
+  // Calculate current width
+  const currentWidth = customWidth ?? (DEVICE_WIDTHS[deviceMode] === '100%' ? null : DEVICE_WIDTHS[deviceMode] as number)
+
+  // Handle escape key and body scroll lock
+  useEffect(() => {
+    if (!isFullscreen) return
+
+    document.body.style.overflow = 'hidden'
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        setIsFullscreen(false)
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown)
+
+    return () => {
+      document.body.style.overflow = ''
+      document.removeEventListener('keydown', handleKeyDown)
+    }
+  }, [isFullscreen])
+
+  // Toggle dark mode on iframe
+  useEffect(() => {
+    const iframe = iframeRef.current
+    if (!iframe) return
+
+    const applyDarkMode = () => {
+      try {
+        const doc = iframe.contentDocument
+        if (doc?.documentElement) {
+          if (isDarkMode) {
+            doc.documentElement.classList.add('dark')
+          } else {
+            doc.documentElement.classList.remove('dark')
+          }
+        }
+      } catch {
+        // Cross-origin iframe, can't access
+      }
+    }
+
+    // Apply on load and when mode changes
+    iframe.addEventListener('load', applyDarkMode)
+    applyDarkMode()
+
+    return () => {
+      iframe.removeEventListener('load', applyDarkMode)
+    }
+  }, [isDarkMode])
+
+  // Drag handlers
+  const handleMouseDown = useCallback((e: React.MouseEvent) => {
+    if (!pillRef.current) return
+    e.preventDefault()
+
+    const rect = pillRef.current.getBoundingClientRect()
+    setDragOffset({
+      x: e.clientX - rect.left,
+      y: e.clientY - rect.top,
+    })
+    setIsDragging(true)
+  }, [])
+
+  useEffect(() => {
+    if (!isDragging) return
+
+    const handleMouseMove = (e: MouseEvent) => {
+      const container = isFullscreen ? document.body : containerRef.current
+      if (!container) return
+
+      const containerRect = isFullscreen
+        ? { left: 0, top: 0, width: window.innerWidth, height: window.innerHeight }
+        : container.getBoundingClientRect()
+
+      const pillWidth = pillRef.current?.offsetWidth || 0
+      const pillHeight = pillRef.current?.offsetHeight || 0
+
+      // Calculate position relative to container
+      let newX = e.clientX - containerRect.left - dragOffset.x
+      let newY = e.clientY - containerRect.top - dragOffset.y
+
+      // Constrain to container bounds
+      newX = Math.max(0, Math.min(newX, containerRect.width - pillWidth))
+      newY = Math.max(0, Math.min(newY, containerRect.height - pillHeight))
+
+      setPillPosition({ x: newX, y: newY })
+    }
+
+    const handleMouseUp = () => {
+      setIsDragging(false)
+    }
+
+    document.addEventListener('mousemove', handleMouseMove)
+    document.addEventListener('mouseup', handleMouseUp)
+
+    return () => {
+      document.removeEventListener('mousemove', handleMouseMove)
+      document.removeEventListener('mouseup', handleMouseUp)
+    }
+  }, [isDragging, dragOffset, isFullscreen])
+
+  // Reset pill position when entering/exiting fullscreen
+  useEffect(() => {
+    setPillPosition({ x: 0, y: 0 })
+  }, [isFullscreen])
+
+  const handleDeviceChange = (mode: DeviceMode) => {
+    setDeviceMode(mode)
+    setCustomWidth(null)
+    setShowSlider(false)
+  }
+
+  const handleSliderChange = (value: number) => {
+    setCustomWidth(value)
+    setDeviceMode('desktop') // Clear device mode when using custom
+  }
+
+  // Icon button component
+  const IconButton = ({
+    onClick,
+    active,
+    title: btnTitle,
+    children
+  }: {
+    onClick: () => void
+    active?: boolean
+    title: string
+    children: React.ReactNode
+  }) => (
+    <button
+      onClick={onClick}
+      className={`p-1.5 rounded transition-colors ${
+        active
+          ? 'bg-blue-500 text-white'
+          : 'text-zinc-500 hover:bg-zinc-200 dark:hover:bg-zinc-700 hover:text-zinc-700 dark:hover:text-zinc-300'
+      }`}
+      title={btnTitle}
+      aria-label={btnTitle}
+    >
+      {children}
+    </button>
+  )
+
+  // Floating DevTools Pill
+  const DevToolsPill = () => {
+    const pillStyle: React.CSSProperties = pillPosition.x === 0 && pillPosition.y === 0
+      ? { bottom: 12, right: 12 }
+      : { left: pillPosition.x, top: pillPosition.y }
+
+    return (
+      <div
+        ref={pillRef}
+        className={`absolute z-50 flex items-center gap-0.5 px-1.5 py-1 bg-white dark:bg-zinc-800 rounded-lg shadow-lg border border-zinc-200 dark:border-zinc-700 ${
+          isDragging ? 'cursor-grabbing' : ''
+        }`}
+        style={pillStyle}
+      >
+        {/* Drag handle */}
+        <div
+          onMouseDown={handleMouseDown}
+          className="p-1 cursor-grab text-zinc-400 hover:text-zinc-600 dark:hover:text-zinc-300"
+          title="Drag to move"
+        >
+          <GripVertical className="w-3 h-3" />
+        </div>
+
+        <div className="w-px h-4 bg-zinc-200 dark:bg-zinc-700 mx-0.5" />
+
+        {/* Device modes */}
+        <IconButton
+          onClick={() => handleDeviceChange('mobile')}
+          active={deviceMode === 'mobile' && customWidth === null}
+          title="Mobile (375px)"
+        >
+          <Smartphone className="w-3.5 h-3.5" />
+        </IconButton>
+
+        <IconButton
+          onClick={() => handleDeviceChange('tablet')}
+          active={deviceMode === 'tablet' && customWidth === null}
+          title="Tablet (768px)"
+        >
+          <Tablet className="w-3.5 h-3.5" />
+        </IconButton>
+
+        <IconButton
+          onClick={() => handleDeviceChange('desktop')}
+          active={deviceMode === 'desktop' && customWidth === null}
+          title="Desktop (100%)"
+        >
+          <Monitor className="w-3.5 h-3.5" />
+        </IconButton>
+
+        <div className="w-px h-4 bg-zinc-200 dark:bg-zinc-700 mx-0.5" />
+
+        {/* Width slider toggle */}
+        <div className="relative">
+          <IconButton
+            onClick={() => setShowSlider(!showSlider)}
+            active={showSlider || customWidth !== null}
+            title="Custom width"
+          >
+            <SlidersHorizontal className="w-3.5 h-3.5" />
+          </IconButton>
+
+          {/* Slider popup */}
+          {showSlider && (
+            <div className="absolute bottom-full left-1/2 -translate-x-1/2 mb-2 p-3 bg-white dark:bg-zinc-800 rounded-lg shadow-lg border border-zinc-200 dark:border-zinc-700 min-w-48">
+              <div className="flex items-center justify-between mb-2">
+                <span className="text-xs text-zinc-500">Width: {customWidth ?? currentWidth ?? '100%'}px</span>
+                <button
+                  onClick={() => setShowSlider(false)}
+                  className="p-0.5 text-zinc-400 hover:text-zinc-600"
+                >
+                  <X className="w-3 h-3" />
+                </button>
+              </div>
+              <input
+                type="range"
+                min={320}
+                max={1920}
+                value={customWidth ?? (typeof currentWidth === 'number' ? currentWidth : 1920)}
+                onChange={(e) => handleSliderChange(parseInt(e.target.value))}
+                className="w-full accent-blue-500"
+              />
+              <div className="flex justify-between text-xs text-zinc-400 mt-1">
+                <span>320px</span>
+                <span>1920px</span>
+              </div>
+            </div>
+          )}
+        </div>
+
+        <div className="w-px h-4 bg-zinc-200 dark:bg-zinc-700 mx-0.5" />
+
+        {/* Dark mode toggle */}
+        <IconButton
+          onClick={() => setIsDarkMode(!isDarkMode)}
+          active={isDarkMode}
+          title={isDarkMode ? 'Light mode' : 'Dark mode'}
+        >
+          {isDarkMode ? <Moon className="w-3.5 h-3.5" /> : <SunMedium className="w-3.5 h-3.5" />}
+        </IconButton>
+
+        {/* Fullscreen toggle */}
+        <IconButton
+          onClick={() => setIsFullscreen(!isFullscreen)}
+          active={isFullscreen}
+          title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+        >
+          {isFullscreen ? <Minimize2 className="w-3.5 h-3.5" /> : <Maximize2 className="w-3.5 h-3.5" />}
+        </IconButton>
+      </div>
+    )
+  }
+
+  // Calculate iframe style
+  const getIframeContainerStyle = (): React.CSSProperties => {
+    if (currentWidth === null) {
+      return { width: '100%' }
+    }
+    return {
+      width: currentWidth,
+      maxWidth: '100%',
+      margin: '0 auto',
+    }
+  }
+
+  if (isFullscreen) {
+    return (
+      <div className="fixed inset-0 z-40 bg-zinc-100 dark:bg-zinc-900 flex items-start justify-center overflow-auto">
+        {/* Checkered background pattern */}
+        <div
+          className="absolute inset-0 opacity-50"
+          style={{
+            backgroundImage: 'linear-gradient(45deg, #e5e5e5 25%, transparent 25%), linear-gradient(-45deg, #e5e5e5 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #e5e5e5 75%), linear-gradient(-45deg, transparent 75%, #e5e5e5 75%)',
+            backgroundSize: '20px 20px',
+            backgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',
+          }}
+        />
+
+        {/* Iframe container */}
+        <div
+          className="relative bg-white dark:bg-zinc-900 shadow-2xl transition-all duration-300 h-full"
+          style={getIframeContainerStyle()}
+        >
+          <iframe
+            ref={iframeRef}
+            src={previewUrl}
+            className="w-full h-full"
+            title={displayTitle}
+          />
+        </div>
+
+        <DevToolsPill />
+      </div>
+    )
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className="my-4 border border-zinc-200 dark:border-zinc-700 rounded-lg overflow-hidden relative"
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between px-3 py-2 bg-zinc-50 dark:bg-zinc-800 border-b border-zinc-200 dark:border-zinc-700">
+        <span className="text-sm font-medium text-zinc-600 dark:text-zinc-400">
+          {displayTitle}
+        </span>
+        <span className="text-xs text-zinc-400">
+          {currentWidth ? `${currentWidth}px` : '100%'}
+        </span>
+      </div>
+
+      {/* Preview area with checkered background */}
+      <div
+        className="relative bg-zinc-100 dark:bg-zinc-900"
+        style={{
+          backgroundImage: 'linear-gradient(45deg, #e5e5e5 25%, transparent 25%), linear-gradient(-45deg, #e5e5e5 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #e5e5e5 75%), linear-gradient(-45deg, transparent 75%, #e5e5e5 75%)',
+          backgroundSize: '16px 16px',
+          backgroundPosition: '0 0, 0 8px, 8px -8px, -8px 0px',
+        }}
+      >
+        {/* Iframe container */}
+        <div
+          className="bg-white dark:bg-zinc-900 transition-all duration-300"
+          style={getIframeContainerStyle()}
+        >
+          <iframe
+            ref={iframeRef}
+            src={previewUrl}
+            style={{ height: typeof height === 'number' ? `${height}px` : height }}
+            className="w-full"
+            title={displayTitle}
+          />
+        </div>
+
+        <DevToolsPill />
+      </div>
+    </div>
+  )
+}

package/src/theme/entry.tsx

@@ -7,10 +7,12 @@ import {
   createRoute,
   Outlet,
 } from '@tanstack/react-router'
+import { MDXProvider } from '@mdx-js/react'
 import { pages, sidebar } from 'virtual:prev-pages'
 import { useDiagrams } from './diagrams'
 import { Layout } from './Layout'
 import { MetadataBlock } from './MetadataBlock'
+import { mdxComponents } from './mdx-components'
 import './styles.css'
 
 // PageTree types (simplified from fumadocs-core)
@@ -72,12 +74,12 @@ interface PageMeta {
 function PageWrapper({ Component, meta }: { Component: React.ComponentType; meta: PageMeta }) {
   useDiagrams()
   return (
-    <>
+    <MDXProvider components={mdxComponents}>
       {meta.frontmatter && Object.keys(meta.frontmatter).length > 0 && (
         <MetadataBlock frontmatter={meta.frontmatter} />
       )}
       <Component />
-    </>
+    </MDXProvider>
   )
 }
 

package/src/theme/mdx-components.tsx

@@ -0,0 +1,5 @@
+import { Preview } from './Preview'
+
+export const mdxComponents = {
+  Preview,
+}