prev-cli 0.19.2 → 0.21.0

package/dist/cli.js

@@ -11,7 +11,7 @@ import { createServer as createServer2, build as build2, preview } from "vite";
 
 // src/vite/config.ts
 import { createLogger } from "vite";
-import react from "@vitejs/plugin-react-swc";
+import react from "@vitejs/plugin-react";
 import mdx from "@mdx-js/rollup";
 import remarkGfm from "remark-gfm";
 import rehypeHighlight from "rehype-highlight";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prev-cli",
-  "version": "0.19.2",
+  "version": "0.21.0",
   "description": "Transform MDX directories into beautiful documentation websites",
   "type": "module",
   "license": "MIT",
@@ -45,9 +45,10 @@
     "@tailwindcss/vite": "^4.0.0",
     "@tanstack/react-router": "^1.145.7",
     "@terrastruct/d2": "^0.1.33",
-    "@vitejs/plugin-react-swc": "^4.2.2",
+    "@vitejs/plugin-react": "^5.1.2",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.0",
+    "esbuild": "^0.27.2",
     "fast-glob": "^3.3.0",
     "fumadocs-core": "^16.4.3",
     "fumadocs-ui": "^16.4.3",
@@ -59,9 +60,9 @@
     "react-router-dom": "^7.0.0",
     "rehype-highlight": "^7.0.0",
     "remark-gfm": "^4.0.0",
-    "rolldown-vite": "^7.3.0",
     "tailwind-merge": "^2.5.0",
-    "tailwindcss": "^4.0.0"
+    "tailwindcss": "^4.0.0",
+    "vite": "npm:rolldown-vite@^7.3.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/theme/DevToolsContext.tsx

@@ -0,0 +1,39 @@
+import React, { createContext, useContext, useState, useCallback } from 'react'
+
+interface DevToolsContextValue {
+  devToolsContent: React.ReactNode | null
+  setDevToolsContent: (content: React.ReactNode | null) => void
+}
+
+const DevToolsContext = createContext<DevToolsContextValue | null>(null)
+
+export function DevToolsProvider({ children }: { children: React.ReactNode }) {
+  const [devToolsContent, setDevToolsContent] = useState<React.ReactNode | null>(null)
+
+  return (
+    <DevToolsContext.Provider value={{ devToolsContent, setDevToolsContent }}>
+      {children}
+    </DevToolsContext.Provider>
+  )
+}
+
+// Fallback for when context isn't available (e.g., SSR or standalone usage)
+const fallbackContext: DevToolsContextValue = {
+  devToolsContent: null,
+  setDevToolsContent: () => {},
+}
+
+export function useDevTools() {
+  const context = useContext(DevToolsContext)
+  // Return fallback instead of throwing - safer for SSR and edge cases
+  return context ?? fallbackContext
+}
+
+export function useRegisterDevTools(content: React.ReactNode | null, deps: any[] = []) {
+  const { setDevToolsContent } = useDevTools()
+
+  React.useEffect(() => {
+    setDevToolsContent(content)
+    return () => setDevToolsContent(null)
+  }, deps)
+}

package/src/theme/Preview.tsx

@@ -1,6 +1,7 @@
 import React, { useState, useEffect, useRef } from 'react'
 import { Link } from '@tanstack/react-router'
 import { Icon, IconSprite } from './icons'
+import { useDevTools } from './DevToolsContext'
 import type { PreviewConfig, PreviewMessage, BuildResult } from '../preview-runtime/types'
 
 interface PreviewProps {
@@ -32,8 +33,16 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
 
   const iframeRef = useRef<HTMLIFrameElement>(null)
 
-  // URL depends on mode - wasm mode needs src param
-  const previewUrl = mode === 'wasm' ? `/_preview-runtime?src=${src}` : `/_preview/${src}`
+  // Get devtools context for toolbar integration
+  const { setDevToolsContent } = useDevTools()
+
+  // In production, always use pre-built static previews
+  // In dev, use WASM runtime for live bundling
+  const isDev = import.meta.env?.DEV ?? false
+  const effectiveMode = isDev ? mode : 'legacy'
+
+  // URL depends on mode - wasm mode needs src param, legacy uses pre-built files
+  const previewUrl = effectiveMode === 'wasm' ? `/_preview-runtime?src=${src}` : `/_preview/${src}/`
   const displayTitle = title || src
 
   // Calculate current width
@@ -89,9 +98,9 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
     }
   }, [isDarkMode])
 
-  // WASM preview: Initialize and send config to iframe
+  // WASM preview: Initialize and send config to iframe (dev mode only)
   useEffect(() => {
-    if (mode !== 'wasm') return
+    if (effectiveMode !== 'wasm') return
 
     const iframe = iframeRef.current
     if (!iframe) return
@@ -141,8 +150,8 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
     }
   }, [mode, src])
 
-  const handleDeviceChange = (mode: DeviceMode) => {
-    setDeviceMode(mode)
+  const handleDeviceChange = (newMode: DeviceMode) => {
+    setDeviceMode(newMode)
     setCustomWidth(null)
     setShowSlider(false)
   }
@@ -152,7 +161,7 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
     setDeviceMode('desktop')
   }
 
-  // Icon button component
+  // Icon button component for devtools
   const IconButton = ({
     onClick,
     active,
@@ -176,7 +185,7 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
         justifyContent: 'center',
         transition: 'background-color 0.15s, color 0.15s',
         backgroundColor: active ? 'var(--fd-primary, #3b82f6)' : 'transparent',
-        color: active ? '#fff' : 'var(--fd-muted-foreground, #71717a)',
+        color: active ? 'var(--fd-primary-foreground, #fff)' : 'var(--fd-muted-foreground, #71717a)',
       }}
       title={btnTitle}
       aria-label={btnTitle}
@@ -275,6 +284,14 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
     </div>
   )
 
+  // Register DevTools in toolbar when on detail page (showHeader mode)
+  useEffect(() => {
+    if (showHeader && !isFullscreen) {
+      setDevToolsContent(<DevTools />)
+      return () => setDevToolsContent(null)
+    }
+  }, [showHeader, isFullscreen, deviceMode, customWidth, showSlider])
+
   // Calculate iframe style
   const getIframeContainerStyle = (): React.CSSProperties => {
     if (currentWidth === null) {
@@ -346,10 +363,11 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
   }
 
   // Non-fullscreen with showHeader (individual preview page)
+  // DevTools are rendered in the toolbar via context, not in this header
   if (showHeader) {
     return (
       <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
-        {/* Header with back button and devtools */}
+        {/* Header with back button and build status - DevTools are in toolbar */}
         <div style={{
           display: 'flex',
           alignItems: 'center',
@@ -357,7 +375,6 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
           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
@@ -385,7 +402,6 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
               <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)' }}>{buildTime}ms</span>
             )}
           </div>
-          <DevTools />
         </div>
 
         {/* Build error display */}

package/src/theme/Toolbar.css

@@ -43,13 +43,53 @@
 }
 
 .toolbar-devtools-slot {
-  display: contents;
+  display: flex;
+  align-items: center;
+  gap: 0.125rem;
+  padding-left: 0.25rem;
+  margin-left: 0.25rem;
+  border-left: 1px solid var(--fd-border);
 }
 
 .toolbar-devtools-slot:empty {
   display: none;
 }
 
+/* Style devtools buttons in toolbar */
+.toolbar-devtools-slot button {
+  width: 32px;
+  height: 32px;
+  padding: 4px;
+  border-radius: 50%;
+  background: transparent;
+  border: none;
+  color: var(--fd-muted-foreground);
+  cursor: pointer;
+  transition: all 0.15s ease;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.toolbar-devtools-slot button:hover {
+  background: var(--fd-muted);
+  color: var(--fd-foreground);
+}
+
+/* Override active state for toolbar devtools buttons */
+.toolbar-devtools-slot button[style*="background-color: var(--fd-primary"] {
+  background: var(--fd-accent) !important;
+  color: var(--fd-accent-foreground) !important;
+}
+
+/* Adjust slider dropdown position when in toolbar (opens upward) */
+.toolbar-devtools-slot [style*="position: absolute"] {
+  bottom: 100% !important;
+  top: auto !important;
+  margin-bottom: 8px !important;
+  margin-top: 0 !important;
+}
+
 /* Hide width toggle on mobile */
 @media (max-width: 768px) {
   .toolbar-btn.desktop-only {

package/src/theme/Toolbar.tsx

@@ -3,6 +3,7 @@ import { Link, useLocation } from '@tanstack/react-router'
 import type { PageTree } from 'fumadocs-core/server'
 import { previews } from 'virtual:prev-previews'
 import { Icon } from './icons'
+import { useDevTools } from './DevToolsContext'
 import './Toolbar.css'
 
 interface ToolbarProps {
@@ -22,6 +23,7 @@ export function Toolbar({ tree, onThemeToggle, onWidthToggle, isDark, isFullWidt
   const toolbarRef = useRef<HTMLDivElement>(null)
   const location = useLocation()
   const isOnPreviews = location.pathname.startsWith('/previews')
+  const { devToolsContent } = useDevTools()
 
   const handleMouseDown = (e: React.MouseEvent) => {
     if ((e.target as HTMLElement).closest('button, a')) return
@@ -70,8 +72,12 @@ export function Toolbar({ tree, onThemeToggle, onWidthToggle, isDark, isFullWidt
         </Link>
       )}
 
-      {/* Contextual devtools slot - populated by preview context */}
-      <div className="toolbar-devtools-slot" id="toolbar-devtools" />
+      {/* Contextual devtools - rendered from preview context */}
+      {devToolsContent && (
+        <div className="toolbar-devtools-slot">
+          {devToolsContent}
+        </div>
+      )}
 
       <button
         className="toolbar-btn desktop-only"

package/src/theme/entry.tsx

@@ -8,6 +8,9 @@ import {
   Outlet,
   redirect,
   Navigate,
+  useLocation,
+  useParams,
+  Link,
 } from '@tanstack/react-router'
 import { MDXProvider } from '@mdx-js/react'
 import { pages, sidebar } from 'virtual:prev-pages'
@@ -17,6 +20,7 @@ import { useDiagrams } from './diagrams'
 import { Layout } from './Layout'
 import { MetadataBlock } from './MetadataBlock'
 import { mdxComponents } from './mdx-components'
+import { DevToolsProvider } from './DevToolsContext'
 import './styles.css'
 
 // PageTree types (simplified from fumadocs-core)
@@ -151,10 +155,61 @@ function PreviewsCatalog() {
   )
 }
 
-// Individual preview card - clickable thumbnail
-import { Link, useParams } from '@tanstack/react-router'
+// Individual preview card - clickable thumbnail with WASM preview communication
+import type { PreviewConfig, PreviewMessage } from '../preview-runtime/types'
 
 function PreviewCard({ name }: { name: string }) {
+  const iframeRef = React.useRef<HTMLIFrameElement>(null)
+  const [isLoaded, setIsLoaded] = React.useState(false)
+
+  // In production, use pre-built static files; in dev, use WASM runtime
+  const isDev = import.meta.env?.DEV ?? false
+  const previewUrl = isDev ? `/_preview-runtime?src=${name}` : `/_preview/${name}/`
+
+  // Set up WASM preview communication for thumbnail (dev mode only)
+  React.useEffect(() => {
+    if (!isDev) {
+      // In production, just mark as loaded when iframe loads
+      const iframe = iframeRef.current
+      if (iframe) {
+        iframe.onload = () => setIsLoaded(true)
+      }
+      return
+    }
+
+    const iframe = iframeRef.current
+    if (!iframe) return
+
+    let configSent = false
+
+    const handleMessage = (event: MessageEvent) => {
+      const msg = event.data as PreviewMessage
+
+      if (msg.type === 'ready' && !configSent) {
+        configSent = true
+
+        fetch(`/_preview-config/${name}`)
+          .then(res => res.json())
+          .then((config: PreviewConfig) => {
+            iframe.contentWindow?.postMessage({ type: 'init', config } as PreviewMessage, '*')
+          })
+          .catch(() => {
+            // Silently fail for thumbnails
+          })
+      }
+
+      if (msg.type === 'built') {
+        setIsLoaded(true)
+      }
+    }
+
+    window.addEventListener('message', handleMessage)
+
+    return () => {
+      window.removeEventListener('message', handleMessage)
+    }
+  }, [name, isDev])
+
   return (
     <Link
       to={`/previews/${name}`}
@@ -185,19 +240,40 @@ function PreviewCard({ name }: { name: string }) {
         backgroundColor: 'var(--fd-muted)',
         pointerEvents: 'none',
       }}>
+        {/* Loading spinner */}
+        {!isLoaded && (
+          <div style={{
+            position: 'absolute',
+            inset: 0,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            backgroundColor: 'var(--fd-muted)',
+            zIndex: 1,
+          }}>
+            <div style={{
+              width: '24px',
+              height: '24px',
+              border: '2px solid var(--fd-border)',
+              borderTopColor: 'var(--fd-primary)',
+              borderRadius: '50%',
+              animation: 'spin 1s linear infinite',
+            }} />
+          </div>
+        )}
         <iframe
-          src={`/_preview-runtime?src=${name}`}
+          ref={iframeRef}
+          src={previewUrl}
           style={{
-            width: '100%',
-            height: '100%',
             border: 'none',
             transform: 'scale(0.5)',
             transformOrigin: 'top left',
             width: '200%',
             height: '200%',
+            opacity: isLoaded ? 1 : 0,
+            transition: 'opacity 0.3s',
           }}
           title={name}
-          loading="lazy"
         />
       </div>
       {/* Card footer */}
@@ -221,15 +297,37 @@ function PreviewCard({ name }: { name: string }) {
   )
 }
 
-// Individual preview page - full view with devtools in header
+// Individual preview page - full view with devtools in toolbar
 function PreviewPage() {
-  const { name } = useParams({ from: '/previews/$name' })
-  return <Preview src={name} height="calc(100vh - 200px)" showHeader />
+  const params = useParams({ strict: false })
+  // Splat param captures the full path after /previews/
+  const name = (params as any)['_splat'] || (params as any)['*'] || params.name as string
+
+  if (!name) {
+    return <Navigate to="/previews" />
+  }
+
+  return (
+    <div className="preview-detail-page">
+      <Preview src={name} height="100%" showHeader />
+    </div>
+  )
 }
 
 // Root layout with custom lightweight Layout
 function RootLayout() {
   const pageTree = convertToPageTree(sidebar)
+  const location = useLocation()
+  const isPreviewDetail = location.pathname.startsWith('/previews/') && location.pathname !== '/previews'
+
+  // Preview detail page gets full viewport layout
+  if (isPreviewDetail) {
+    return (
+      <Layout tree={pageTree}>
+        <Outlet />
+      </Layout>
+    )
+  }
 
   return (
     <Layout tree={pageTree}>
@@ -252,10 +350,10 @@ const previewsRoute = createRoute({
   component: PreviewsCatalog,
 })
 
-// Individual preview route
+// Individual preview route (uses splat to capture nested paths like buttons/primary)
 const previewDetailRoute = createRoute({
   getParentRoute: () => rootRoute,
-  path: '/previews/$name',
+  path: '/previews/$',
   component: PreviewPage,
 })
 
@@ -307,5 +405,9 @@ const router = createRouter({
 const container = document.getElementById('root')
 if (container) {
   const root = createRoot(container)
-  root.render(<RouterProvider router={router} />)
+  root.render(
+    <DevToolsProvider>
+      <RouterProvider router={router} />
+    </DevToolsProvider>
+  )
 }

package/src/theme/styles.css

@@ -523,6 +523,13 @@ body {
   max-width: 100%;
 }
 
+/* Mobile: add bottom padding for floating toolbar */
+@media (max-width: 768px) {
+  .prev-main-floating {
+    padding-bottom: 5rem;
+  }
+}
+
 .prev-main-floating .prev-content {
   max-width: 72ch;
   margin: 0 auto;
@@ -531,3 +538,32 @@ body {
 .full-width .prev-main-floating .prev-content {
   max-width: none;
 }
+
+/* Preview detail page - full available space */
+.preview-detail-page {
+  height: calc(100vh - 4rem);
+  padding: 0;
+  margin: -2rem; /* Negate parent padding */
+  margin-bottom: 3rem; /* Space for toolbar */
+}
+
+.preview-detail-page > div {
+  height: 100%;
+  border-radius: 0;
+  overflow: hidden;
+}
+
+@media (min-width: 769px) {
+  .preview-detail-page {
+    margin: -2rem;
+    margin-bottom: 0;
+    height: calc(100vh - 2rem);
+    padding: 1rem;
+  }
+
+  .preview-detail-page > div {
+    border-radius: 12px;
+    border: 1px solid var(--fd-border);
+    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08);
+  }
+}