prev-cli 0.16.0 → 0.16.2

package/dist/cli.js

@@ -961,6 +961,12 @@ async function createViteConfig(options) {
         "mermaid",
         "dayjs",
         "@terrastruct/d2"
+      ],
+      exclude: [
+        "virtual:prev-config",
+        "virtual:prev-previews",
+        "virtual:prev-pages",
+        "@prev/theme"
       ]
     },
     ssr: {
@@ -1279,10 +1285,18 @@ Examples:
   prev clean -d 7            Remove caches older than 7 days
 `);
 }
-function clearViteCache(rootDir2) {
+async function clearViteCache(rootDir2) {
+  let cleared = 0;
+  try {
+    const prevCacheDir = await getCacheDir(rootDir2);
+    if (existsSync7(prevCacheDir)) {
+      rmSync3(prevCacheDir, { recursive: true });
+      cleared++;
+      console.log(`  ✓ Removed ${prevCacheDir}`);
+    }
+  } catch {}
   const viteCacheDir = path9.join(rootDir2, ".vite");
   const nodeModulesVite = path9.join(rootDir2, "node_modules", ".vite");
-  let cleared = 0;
   if (existsSync7(viteCacheDir)) {
     rmSync3(viteCacheDir, { recursive: true });
     cleared++;
@@ -1476,7 +1490,7 @@ async function main() {
         createPreview(rootDir, previewName);
         break;
       case "clearcache":
-        clearViteCache(rootDir);
+        await clearViteCache(rootDir);
         break;
       default:
         console.error(`Unknown command: ${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prev-cli",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Transform MDX directories into beautiful documentation websites",
   "type": "module",
   "license": "MIT",

package/src/theme/Preview.tsx

@@ -1,12 +1,14 @@
-import React, { useState, useEffect, useRef, useCallback } from 'react'
-import { Smartphone, Tablet, Monitor, SunMedium, Moon, Maximize2, Minimize2, GripVertical, SlidersHorizontal, X, Loader2 } from 'lucide-react'
+import React, { useState, useEffect, useRef } from 'react'
+import { IconDeviceMobile, IconDeviceTablet, IconDeviceDesktop, IconArrowsMaximize, IconArrowsMinimize, IconAdjustmentsHorizontal, IconX, IconLoader2, IconArrowLeft } from '@tabler/icons-react'
+import { Link } from '@tanstack/react-router'
 import type { PreviewConfig, PreviewMessage, BuildResult } from '../preview-runtime/types'
 
 interface PreviewProps {
   src: string
   height?: string | number
   title?: string
-  mode?: 'wasm' | 'legacy' // 'wasm' uses browser bundling, 'legacy' uses Vite
+  mode?: 'wasm' | 'legacy'
+  showHeader?: boolean // Show full header with back button and devtools
 }
 
 type DeviceMode = 'mobile' | 'tablet' | 'desktop'
@@ -17,20 +19,11 @@ const DEVICE_WIDTHS: Record<DeviceMode, number | '100%'> = {
   desktop: '100%',
 }
 
-interface Position {
-  x: number
-  y: number
-}
-
-export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProps) {
+export function Preview({ src, height = 400, title, mode = 'wasm', showHeader = false }: 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 })
 
   // WASM preview state
   const [buildStatus, setBuildStatus] = useState<'loading' | 'building' | 'ready' | 'error'>('loading')
@@ -38,8 +31,6 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
   const [buildError, setBuildError] = useState<string | null>(null)
 
   const iframeRef = useRef<HTMLIFrameElement>(null)
-  const pillRef = useRef<HTMLDivElement>(null)
-  const containerRef = useRef<HTMLDivElement>(null)
 
   // URL depends on mode
   const previewUrl = mode === 'wasm' ? '/_preview-runtime' : `/_preview/${src}`
@@ -48,6 +39,9 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
   // Calculate current width
   const currentWidth = customWidth ?? (DEVICE_WIDTHS[deviceMode] === '100%' ? null : DEVICE_WIDTHS[deviceMode] as number)
 
+  // Use master dark mode from document
+  const isDarkMode = typeof document !== 'undefined' && document.documentElement.classList.contains('dark')
+
   // Handle escape key and body scroll lock
   useEffect(() => {
     if (!isFullscreen) return
@@ -67,7 +61,7 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
     }
   }, [isFullscreen])
 
-  // Toggle dark mode on iframe
+  // Apply dark mode to iframe content
   useEffect(() => {
     const iframe = iframeRef.current
     if (!iframe) return
@@ -83,11 +77,10 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
           }
         }
       } catch {
-        // Cross-origin iframe, can't access
+        // Cross-origin iframe
       }
     }
 
-    // Apply on load and when mode changes
     iframe.addEventListener('load', applyDarkMode)
     applyDarkMode()
 
@@ -105,12 +98,10 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
 
     let configSent = false
 
-    // Handle messages from iframe
     const handleMessage = (event: MessageEvent) => {
       const msg = event.data as PreviewMessage
 
       if (msg.type === 'ready' && !configSent) {
-        // Iframe is ready, fetch and send config
         configSent = true
         setBuildStatus('building')
 
@@ -150,62 +141,6 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
     }
   }, [mode, src])
 
-  // 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)
@@ -214,10 +149,10 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
 
   const handleSliderChange = (value: number) => {
     setCustomWidth(value)
-    setDeviceMode('desktop') // Clear device mode when using custom
+    setDeviceMode('desktop')
   }
 
-  // Icon button component - using inline styles since Tailwind isn't enabled for docs
+  // Icon button component
   const IconButton = ({
     onClick,
     active,
@@ -240,8 +175,8 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
         alignItems: 'center',
         justifyContent: 'center',
         transition: 'background-color 0.15s, color 0.15s',
-        backgroundColor: active ? '#3b82f6' : 'transparent',
-        color: active ? '#fff' : '#71717a',
+        backgroundColor: active ? 'var(--fd-primary, #3b82f6)' : 'transparent',
+        color: active ? '#fff' : 'var(--fd-muted-foreground, #71717a)',
       }}
       title={btnTitle}
       aria-label={btnTitle}
@@ -250,147 +185,95 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
     </button>
   )
 
-  // Floating DevTools Pill - using inline styles since Tailwind isn't enabled for docs
-  const DevToolsPill = () => {
-    const baseStyle: React.CSSProperties = {
-      position: 'absolute',
-      zIndex: 50,
-      display: 'flex',
-      alignItems: 'center',
-      gap: '2px',
-      padding: '4px 6px',
-      backgroundColor: '#fff',
-      borderRadius: '8px',
-      boxShadow: '0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06)',
-      border: '1px solid #e4e4e7',
-    }
-
-    const positionStyle: React.CSSProperties = pillPosition.x === 0 && pillPosition.y === 0
-      ? { bottom: 12, right: 12 }
-      : { left: pillPosition.x, top: pillPosition.y }
-
-    const dividerStyle: React.CSSProperties = {
-      width: '1px',
-      height: '16px',
-      backgroundColor: '#e4e4e7',
-      margin: '0 2px',
-    }
-
-    return (
-      <div
-        ref={pillRef}
-        style={{ ...baseStyle, ...positionStyle, cursor: isDragging ? 'grabbing' : undefined }}
+  // DevTools in header - device modes, width slider, fullscreen
+  const DevTools = () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '2px' }}>
+      <IconButton
+        onClick={() => handleDeviceChange('mobile')}
+        active={deviceMode === 'mobile' && customWidth === null}
+        title="Mobile (375px)"
       >
-        {/* Drag handle */}
-        <div
-          onMouseDown={handleMouseDown}
-          style={{ padding: '4px', cursor: 'grab', color: '#a1a1aa' }}
-          title="Drag to move"
-        >
-          <GripVertical style={{ width: 12, height: 12 }} />
-        </div>
+        <IconDeviceMobile size={16} />
+      </IconButton>
 
-        <div style={dividerStyle} />
+      <IconButton
+        onClick={() => handleDeviceChange('tablet')}
+        active={deviceMode === 'tablet' && customWidth === null}
+        title="Tablet (768px)"
+      >
+        <IconDeviceTablet size={16} />
+      </IconButton>
 
-        {/* Device modes */}
-        <IconButton
-          onClick={() => handleDeviceChange('mobile')}
-          active={deviceMode === 'mobile' && customWidth === null}
-          title="Mobile (375px)"
-        >
-          <Smartphone style={{ width: 14, height: 14 }} />
-        </IconButton>
+      <IconButton
+        onClick={() => handleDeviceChange('desktop')}
+        active={deviceMode === 'desktop' && customWidth === null}
+        title="Desktop (100%)"
+      >
+        <IconDeviceDesktop size={16} />
+      </IconButton>
 
-        <IconButton
-          onClick={() => handleDeviceChange('tablet')}
-          active={deviceMode === 'tablet' && customWidth === null}
-          title="Tablet (768px)"
-        >
-          <Tablet style={{ width: 14, height: 14 }} />
-        </IconButton>
+      <div style={{ width: '1px', height: '16px', backgroundColor: 'var(--fd-border, #e4e4e7)', margin: '0 4px' }} />
 
+      {/* Width slider toggle */}
+      <div style={{ position: 'relative' }}>
         <IconButton
-          onClick={() => handleDeviceChange('desktop')}
-          active={deviceMode === 'desktop' && customWidth === null}
-          title="Desktop (100%)"
+          onClick={() => setShowSlider(!showSlider)}
+          active={showSlider || customWidth !== null}
+          title="Custom width"
         >
-          <Monitor style={{ width: 14, height: 14 }} />
+          <IconAdjustmentsHorizontal size={16} />
         </IconButton>
 
-        <div style={dividerStyle} />
-
-        {/* Width slider toggle */}
-        <div style={{ position: 'relative' }}>
-          <IconButton
-            onClick={() => setShowSlider(!showSlider)}
-            active={showSlider || customWidth !== null}
-            title="Custom width"
-          >
-            <SlidersHorizontal style={{ width: 14, height: 14 }} />
-          </IconButton>
-
-          {/* Slider popup */}
-          {showSlider && (
-            <div style={{
-              position: 'absolute',
-              bottom: '100%',
-              left: '50%',
-              transform: 'translateX(-50%)',
-              marginBottom: '8px',
-              padding: '12px',
-              backgroundColor: '#fff',
-              borderRadius: '8px',
-              boxShadow: '0 4px 6px -1px rgba(0,0,0,0.1)',
-              border: '1px solid #e4e4e7',
-              minWidth: '192px',
-            }}>
-              <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: '8px' }}>
-                <span style={{ fontSize: '12px', color: '#71717a' }}>Width: {customWidth ?? currentWidth ?? '100%'}px</span>
-                <button
-                  onClick={() => setShowSlider(false)}
-                  style={{ padding: '2px', background: 'none', border: 'none', cursor: 'pointer', color: '#a1a1aa' }}
-                >
-                  <X style={{ width: 12, height: 12 }} />
-                </button>
-              </div>
-              <input
-                type="range"
-                min={320}
-                max={1920}
-                value={customWidth ?? (typeof currentWidth === 'number' ? currentWidth : 1920)}
-                onChange={(e) => handleSliderChange(parseInt(e.target.value))}
-                style={{ width: '100%', accentColor: '#3b82f6' }}
-              />
-              <div style={{ display: 'flex', justifyContent: 'space-between', fontSize: '12px', color: '#a1a1aa', marginTop: '4px' }}>
-                <span>320px</span>
-                <span>1920px</span>
-              </div>
+        {showSlider && (
+          <div style={{
+            position: 'absolute',
+            top: '100%',
+            right: 0,
+            marginTop: '8px',
+            padding: '12px',
+            backgroundColor: 'var(--fd-background, #fff)',
+            borderRadius: '8px',
+            boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
+            border: '1px solid var(--fd-border, #e4e4e7)',
+            minWidth: '192px',
+            zIndex: 100,
+          }}>
+            <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: '8px' }}>
+              <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #71717a)' }}>
+                Width: {customWidth ?? currentWidth ?? '100%'}px
+              </span>
+              <button
+                onClick={() => setShowSlider(false)}
+                style={{ padding: '2px', background: 'none', border: 'none', cursor: 'pointer', color: 'var(--fd-muted-foreground, #a1a1aa)' }}
+              >
+                <IconX size={12} />
+              </button>
             </div>
-          )}
-        </div>
-
-        <div style={dividerStyle} />
-
-        {/* Dark mode toggle */}
-        <IconButton
-          onClick={() => setIsDarkMode(!isDarkMode)}
-          active={isDarkMode}
-          title={isDarkMode ? 'Light mode' : 'Dark mode'}
-        >
-          {isDarkMode ? <Moon style={{ width: 14, height: 14 }} /> : <SunMedium style={{ width: 14, height: 14 }} />}
-        </IconButton>
-
-        {/* Fullscreen toggle */}
-        <IconButton
-          onClick={() => setIsFullscreen(!isFullscreen)}
-          active={isFullscreen}
-          title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
-        >
-          {isFullscreen ? <Minimize2 style={{ width: 14, height: 14 }} /> : <Maximize2 style={{ width: 14, height: 14 }} />}
-        </IconButton>
+            <input
+              type="range"
+              min={320}
+              max={1920}
+              value={customWidth ?? (typeof currentWidth === 'number' ? currentWidth : 1920)}
+              onChange={(e) => handleSliderChange(parseInt(e.target.value))}
+              style={{ width: '100%', accentColor: 'var(--fd-primary, #3b82f6)' }}
+            />
+            <div style={{ display: 'flex', justifyContent: 'space-between', fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)', marginTop: '4px' }}>
+              <span>320px</span>
+              <span>1920px</span>
+            </div>
+          </div>
+        )}
       </div>
-    )
-  }
+
+      <IconButton
+        onClick={() => setIsFullscreen(!isFullscreen)}
+        active={isFullscreen}
+        title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+      >
+        {isFullscreen ? <IconArrowsMinimize size={16} /> : <IconArrowsMaximize size={16} />}
+      </IconButton>
+    </div>
+  )
 
   // Calculate iframe style
   const getIframeContainerStyle = (): React.CSSProperties => {
@@ -409,75 +292,179 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
       <div style={{
         position: 'fixed',
         inset: 0,
-        zIndex: 40,
-        backgroundColor: '#f4f4f5',
+        zIndex: 9999,
+        backgroundColor: 'var(--fd-muted, #f4f4f5)',
         display: 'flex',
-        alignItems: 'flex-start',
-        justifyContent: 'center',
-        overflow: 'auto',
+        flexDirection: 'column',
       }}>
-        {/* Checkered background pattern */}
-        <div
-          style={{
-            position: 'absolute',
-            inset: 0,
-            opacity: 0.5,
-            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
-          style={{
-            position: 'relative',
-            backgroundColor: '#fff',
-            boxShadow: '0 25px 50px -12px rgba(0,0,0,0.25)',
-            transition: 'all 0.3s',
+        {/* Fullscreen header */}
+        <div style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          padding: '12px 16px',
+          backgroundColor: 'var(--fd-background, #fff)',
+          borderBottom: '1px solid var(--fd-border, #e4e4e7)',
+        }}>
+          <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+            <span style={{ fontSize: '16px', fontWeight: 600, color: 'var(--fd-foreground)' }}>
+              {displayTitle}
+            </span>
+            {mode === 'wasm' && buildTime && (
+              <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)' }}>{buildTime}ms</span>
+            )}
+          </div>
+          <DevTools />
+        </div>
+
+        {/* Checkered background */}
+        <div style={{
+          flex: 1,
+          position: 'relative',
+          backgroundImage: 'linear-gradient(45deg, var(--fd-border, #e5e5e5) 25%, transparent 25%), linear-gradient(-45deg, var(--fd-border, #e5e5e5) 25%, transparent 25%), linear-gradient(45deg, transparent 75%, var(--fd-border, #e5e5e5) 75%), linear-gradient(-45deg, transparent 75%, var(--fd-border, #e5e5e5) 75%)',
+          backgroundSize: '20px 20px',
+          backgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',
+          display: 'flex',
+          justifyContent: 'center',
+        }}>
+          <div style={{
+            backgroundColor: 'var(--fd-background, #fff)',
+            boxShadow: '0 4px 24px rgba(0,0,0,0.1)',
             height: '100%',
             ...getIframeContainerStyle(),
-          }}
-        >
-          <iframe
-            ref={iframeRef}
-            src={previewUrl}
-            style={{ width: '100%', height: '100%', border: 'none' }}
-            title={displayTitle}
-          />
+          }}>
+            <iframe
+              ref={iframeRef}
+              src={previewUrl}
+              style={{ width: '100%', height: '100%', border: 'none' }}
+              title={displayTitle}
+            />
+          </div>
         </div>
+      </div>
+    )
+  }
+
+  // Non-fullscreen with showHeader (individual preview page)
+  if (showHeader) {
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+        {/* Header with back button and devtools */}
+        <div style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          padding: '12px 16px',
+          backgroundColor: 'var(--fd-card, #fafafa)',
+          borderBottom: '1px solid var(--fd-border, #e4e4e7)',
+          borderRadius: '8px 8px 0 0',
+        }}>
+          <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+            <Link
+              to="/previews"
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: '4px',
+                color: 'var(--fd-muted-foreground, #71717a)',
+                textDecoration: 'none',
+                fontSize: '14px',
+              }}
+            >
+              <IconArrowLeft size={16} />
+              Back
+            </Link>
+            <div style={{ width: '1px', height: '20px', backgroundColor: 'var(--fd-border, #e4e4e7)' }} />
+            <span style={{ fontSize: '16px', fontWeight: 600, color: 'var(--fd-foreground)' }}>
+              {displayTitle}
+            </span>
+            {mode === 'wasm' && buildStatus === 'building' && (
+              <IconLoader2 size={16} style={{ color: 'var(--fd-primary, #3b82f6)', animation: 'spin 1s linear infinite' }} />
+            )}
+            {mode === 'wasm' && buildTime && (
+              <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)' }}>{buildTime}ms</span>
+            )}
+          </div>
+          <DevTools />
+        </div>
+
+        {/* Build error display */}
+        {mode === 'wasm' && buildError && (
+          <div style={{
+            padding: '8px 12px',
+            backgroundColor: '#fef2f2',
+            borderBottom: '1px solid #fecaca',
+          }}>
+            <pre style={{
+              fontSize: '12px',
+              color: '#dc2626',
+              whiteSpace: 'pre-wrap',
+              fontFamily: 'monospace',
+              overflow: 'auto',
+              maxHeight: '128px',
+              margin: 0,
+            }}>
+              {buildError}
+            </pre>
+          </div>
+        )}
 
-        <DevToolsPill />
+        {/* Preview area with checkered background */}
+        <div style={{
+          flex: 1,
+          position: 'relative',
+          backgroundColor: 'var(--fd-muted, #f4f4f5)',
+          backgroundImage: 'linear-gradient(45deg, var(--fd-border, #e5e5e5) 25%, transparent 25%), linear-gradient(-45deg, var(--fd-border, #e5e5e5) 25%, transparent 25%), linear-gradient(45deg, transparent 75%, var(--fd-border, #e5e5e5) 75%), linear-gradient(-45deg, transparent 75%, var(--fd-border, #e5e5e5) 75%)',
+          backgroundSize: '16px 16px',
+          backgroundPosition: '0 0, 0 8px, 8px -8px, -8px 0px',
+          display: 'flex',
+          justifyContent: 'center',
+        }}>
+          <div style={{
+            backgroundColor: 'var(--fd-background, #fff)',
+            transition: 'all 0.3s',
+            ...getIframeContainerStyle(),
+          }}>
+            <iframe
+              ref={iframeRef}
+              src={previewUrl}
+              style={{
+                height: typeof height === 'number' ? `${height}px` : height,
+                width: '100%',
+                border: 'none',
+              }}
+              title={displayTitle}
+            />
+          </div>
+        </div>
       </div>
     )
   }
 
+  // Embedded preview (no header, compact)
   return (
-    <div
-      ref={containerRef}
-      style={{
-        margin: '16px 0',
-        border: '1px solid #e4e4e7',
-        borderRadius: '8px',
-        overflow: 'hidden',
-        position: 'relative',
-      }}
-    >
-      {/* Header */}
+    <div style={{
+      margin: '16px 0',
+      border: '1px solid var(--fd-border, #e4e4e7)',
+      borderRadius: '8px',
+      overflow: 'hidden',
+      position: 'relative',
+    }}>
+      {/* Compact header */}
       <div style={{
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'space-between',
         padding: '8px 12px',
-        backgroundColor: '#fafafa',
-        borderBottom: '1px solid #e4e4e7',
+        backgroundColor: 'var(--fd-card, #fafafa)',
+        borderBottom: '1px solid var(--fd-border, #e4e4e7)',
       }}>
         <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
-          <span style={{ fontSize: '14px', fontWeight: 500, color: '#52525b' }}>
+          <span style={{ fontSize: '14px', fontWeight: 500, color: 'var(--fd-foreground, #52525b)' }}>
             {displayTitle}
           </span>
           {mode === 'wasm' && buildStatus === 'building' && (
-            <Loader2 style={{ width: 14, height: 14, color: '#3b82f6', animation: 'spin 1s linear infinite' }} />
+            <IconLoader2 size={14} style={{ color: 'var(--fd-primary, #3b82f6)', animation: 'spin 1s linear infinite' }} />
           )}
           {mode === 'wasm' && buildStatus === 'error' && (
             <span style={{ fontSize: '12px', color: '#ef4444' }}>Error</span>
@@ -485,11 +472,12 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
         </div>
         <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
           {mode === 'wasm' && buildTime && (
-            <span style={{ fontSize: '12px', color: '#a1a1aa' }}>{buildTime}ms</span>
+            <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)' }}>{buildTime}ms</span>
           )}
-          <span style={{ fontSize: '12px', color: '#a1a1aa' }}>
+          <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)' }}>
             {currentWidth ? `${currentWidth}px` : '100%'}
           </span>
+          <DevTools />
         </div>
       </div>
 
@@ -514,24 +502,21 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
         </div>
       )}
 
-      {/* Preview area with checkered background */}
-      <div
-        style={{
-          position: 'relative',
-          backgroundColor: '#f4f4f5',
-          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
-          style={{
-            backgroundColor: '#fff',
-            transition: 'all 0.3s',
-            ...getIframeContainerStyle(),
-          }}
-        >
+      {/* Preview area */}
+      <div style={{
+        position: 'relative',
+        backgroundColor: 'var(--fd-muted, #f4f4f5)',
+        backgroundImage: 'linear-gradient(45deg, var(--fd-border, #e5e5e5) 25%, transparent 25%), linear-gradient(-45deg, var(--fd-border, #e5e5e5) 25%, transparent 25%), linear-gradient(45deg, transparent 75%, var(--fd-border, #e5e5e5) 75%), linear-gradient(-45deg, transparent 75%, var(--fd-border, #e5e5e5) 75%)',
+        backgroundSize: '16px 16px',
+        backgroundPosition: '0 0, 0 8px, 8px -8px, -8px 0px',
+        display: 'flex',
+        justifyContent: 'center',
+      }}>
+        <div style={{
+          backgroundColor: 'var(--fd-background, #fff)',
+          transition: 'all 0.3s',
+          ...getIframeContainerStyle(),
+        }}>
           <iframe
             ref={iframeRef}
             src={previewUrl}
@@ -543,8 +528,6 @@ export function Preview({ src, height = 400, title, mode = 'wasm' }: PreviewProp
             title={displayTitle}
           />
         </div>
-
-        <DevToolsPill />
       </div>
     </div>
   )

package/src/theme/entry.tsx

@@ -85,7 +85,7 @@ function PageWrapper({ Component, meta }: { Component: React.ComponentType; meta
   )
 }
 
-// Previews catalog - Storybook-like gallery
+// Previews catalog - Storybook-like gallery with clickable cards
 function PreviewsCatalog() {
   if (!previews || previews.length === 0) {
     return (
@@ -116,53 +116,31 @@ function PreviewsCatalog() {
           Previews
         </h1>
         <p style={{ color: '#666' }}>
-          {previews.length} component preview{previews.length !== 1 ? 's' : ''} available
+          {previews.length} component preview{previews.length !== 1 ? 's' : ''} available.
+          Click any preview to open it.
         </p>
       </div>
 
       <div style={{
         display: 'grid',
-        gridTemplateColumns: 'repeat(auto-fill, minmax(400px, 1fr))',
-        gap: '24px',
+        gridTemplateColumns: 'repeat(auto-fill, minmax(320px, 1fr))',
+        gap: '20px',
       }}>
         {previews.map((preview: { name: string; route: string }) => (
-          <div key={preview.name} style={{
-            border: '1px solid #e4e4e7',
-            borderRadius: '12px',
-            overflow: 'hidden',
-            backgroundColor: '#fff',
-          }}>
-            <div style={{
-              padding: '12px 16px',
-              borderBottom: '1px solid #e4e4e7',
-              backgroundColor: '#fafafa',
-            }}>
-              <h2 style={{ fontSize: '16px', fontWeight: 600, margin: 0 }}>
-                {preview.name}
-              </h2>
-              <code style={{
-                fontSize: '12px',
-                color: '#666',
-                fontFamily: 'monospace',
-              }}>
-                previews/{preview.name}/
-              </code>
-            </div>
-            <Preview src={preview.name} height={300} />
-          </div>
+          <PreviewCard key={preview.name} name={preview.name} />
         ))}
       </div>
 
       <div style={{
         marginTop: '40px',
         padding: '16px',
-        backgroundColor: '#f0f9ff',
-        border: '1px solid #bae6fd',
+        backgroundColor: 'var(--fd-muted)',
+        border: '1px solid var(--fd-border)',
         borderRadius: '8px',
       }}>
-        <p style={{ margin: 0, fontSize: '14px', color: '#0369a1' }}>
+        <p style={{ margin: 0, fontSize: '14px', color: 'var(--fd-muted-foreground)' }}>
           <strong>Tip:</strong> Embed any preview in your MDX docs with{' '}
-          <code style={{ backgroundColor: '#e0f2fe', padding: '2px 6px', borderRadius: '4px' }}>
+          <code style={{ backgroundColor: 'var(--fd-accent)', padding: '2px 6px', borderRadius: '4px' }}>
             {'<Preview src="name" />'}
           </code>
         </p>
@@ -171,6 +149,82 @@ function PreviewsCatalog() {
   )
 }
 
+// Individual preview card - clickable thumbnail
+import { Link, useParams } from '@tanstack/react-router'
+
+function PreviewCard({ name }: { name: string }) {
+  return (
+    <Link
+      to={`/previews/${name}`}
+      style={{
+        display: 'block',
+        border: '1px solid var(--fd-border)',
+        borderRadius: '12px',
+        overflow: 'hidden',
+        backgroundColor: 'var(--fd-background)',
+        textDecoration: 'none',
+        color: 'inherit',
+        transition: 'box-shadow 0.2s, transform 0.2s',
+      }}
+      onMouseOver={(e) => {
+        e.currentTarget.style.boxShadow = '0 8px 24px rgba(0,0,0,0.12)'
+        e.currentTarget.style.transform = 'translateY(-2px)'
+      }}
+      onMouseOut={(e) => {
+        e.currentTarget.style.boxShadow = ''
+        e.currentTarget.style.transform = ''
+      }}
+    >
+      {/* Thumbnail preview */}
+      <div style={{
+        height: '180px',
+        overflow: 'hidden',
+        position: 'relative',
+        backgroundColor: 'var(--fd-muted)',
+        pointerEvents: 'none',
+      }}>
+        <iframe
+          src={`/_preview-runtime?src=${name}`}
+          style={{
+            width: '100%',
+            height: '100%',
+            border: 'none',
+            transform: 'scale(0.5)',
+            transformOrigin: 'top left',
+            width: '200%',
+            height: '200%',
+          }}
+          title={name}
+          loading="lazy"
+        />
+      </div>
+      {/* Card footer */}
+      <div style={{
+        padding: '12px 16px',
+        borderTop: '1px solid var(--fd-border)',
+        backgroundColor: 'var(--fd-card)',
+      }}>
+        <h3 style={{ fontSize: '14px', fontWeight: 600, margin: 0 }}>
+          {name}
+        </h3>
+        <code style={{
+          fontSize: '11px',
+          color: 'var(--fd-muted-foreground)',
+          fontFamily: 'monospace',
+        }}>
+          previews/{name}/
+        </code>
+      </div>
+    </Link>
+  )
+}
+
+// Individual preview page - full view with devtools in header
+function PreviewPage() {
+  const { name } = useParams({ from: '/previews/$name' })
+  return <Preview src={name} height="calc(100vh - 200px)" showHeader />
+}
+
 // Root layout with custom lightweight Layout
 function RootLayout() {
   const pageTree = convertToPageTree(sidebar)
@@ -196,6 +250,13 @@ const previewsRoute = createRoute({
   component: PreviewsCatalog,
 })
 
+// Individual preview route
+const previewDetailRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/previews/$name',
+  component: PreviewPage,
+})
+
 // Create routes from pages
 const pageRoutes = pages.map((page: { route: string; file: string; title?: string; description?: string; frontmatter?: Record<string, unknown> }) => {
   const Component = getPageComponent(page.file)
@@ -212,7 +273,7 @@ const pageRoutes = pages.map((page: { route: string; file: string; title?: strin
 })
 
 // Create router
-const routeTree = rootRoute.addChildren([previewsRoute, ...pageRoutes])
+const routeTree = rootRoute.addChildren([previewsRoute, previewDetailRoute, ...pageRoutes])
 const router = createRouter({ routeTree })
 
 // Mount app - RouterProvider must be outermost so TanStack Router context is available