prev-cli 0.22.4 → 0.24.0

package/dist/cli.js

@@ -130,13 +130,18 @@ function isIndexFile(basename) {
   const lower = basename.toLowerCase();
   return lower === "index" || lower === "readme";
 }
+var CONTENT_ROOT_DIRS = ["docs", "documentation", "content", "pages"];
 function fileToRoute(file) {
-  const normalizedFile = file.replace(/^\./, "").replace(/\/\./g, "/");
+  let normalizedFile = file.replace(/^\./, "").replace(/\/\./g, "/");
+  const firstDir = normalizedFile.split("/")[0]?.toLowerCase();
+  if (CONTENT_ROOT_DIRS.includes(firstDir)) {
+    normalizedFile = normalizedFile.slice(firstDir.length + 1) || normalizedFile;
+  }
   const withoutExt = normalizedFile.replace(/\.mdx?$/, "");
   const basename = path2.basename(withoutExt).toLowerCase();
   if (basename === "index" || basename === "readme") {
     const dir = path2.dirname(withoutExt);
-    if (dir === ".") {
+    if (dir === "." || dir === "") {
       return "/";
     }
     return "/" + dir;
@@ -867,13 +872,14 @@ var cliRoot2 = findCliRoot2();
 var cliNodeModules = findNodeModules(cliRoot2);
 var srcRoot2 = path8.join(cliRoot2, "src");
 async function createViteConfig(options) {
-  const { rootDir, mode, port, include } = options;
+  const { rootDir, mode, port, include, base } = options;
   const cacheDir = await ensureCacheDir(rootDir);
   const config = loadConfig(rootDir);
   return {
     root: rootDir,
     mode,
     cacheDir,
+    base: base || "/",
     customLogger: createFriendlyLogger(),
     logLevel: mode === "production" ? "silent" : "info",
     plugins: [
@@ -1118,7 +1124,7 @@ async function findAvailablePort(minPort, maxPort) {
 
 // src/vite/start.ts
 import { exec as exec2 } from "child_process";
-import { existsSync as existsSync6, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync6, rmSync as rmSync2, copyFileSync } from "fs";
 import path9 from "path";
 function printWelcome(type) {
   console.log();
@@ -1224,9 +1230,16 @@ async function buildSite(rootDir, options = {}) {
   const config = await createViteConfig({
     rootDir,
     mode: "production",
-    include: options.include
+    include: options.include,
+    base: options.base
   });
   await build2(config);
+  const distDir = path9.join(rootDir, "dist");
+  const indexPath = path9.join(distDir, "index.html");
+  const notFoundPath = path9.join(distDir, "404.html");
+  if (existsSync6(indexPath)) {
+    copyFileSync(indexPath, notFoundPath);
+  }
   console.log();
   console.log("  Done! Your site is ready in ./dist");
   console.log("  You can deploy this folder anywhere.");
@@ -1272,6 +1285,7 @@ var { values, positionals } = parseArgs({
     port: { type: "string", short: "p" },
     days: { type: "string", short: "d" },
     cwd: { type: "string", short: "c" },
+    base: { type: "string", short: "b" },
     help: { type: "boolean", short: "h" },
     version: { type: "boolean", short: "v" }
   },
@@ -1301,6 +1315,7 @@ Config subcommands:
 Options:
   -c, --cwd <path>       Set working directory
   -p, --port <port>      Specify port (dev/preview)
+  -b, --base <path>      Base path for deployment (e.g., /repo-name/ for GitHub Pages)
   -d, --days <days>      Cache age threshold for clean (default: 30)
   -h, --help             Show this help message
   -v, --version          Show version number
@@ -1660,7 +1675,7 @@ async function main() {
         await startDev(rootDir, { port, include });
         break;
       case "build":
-        await buildSite(rootDir, { include });
+        await buildSite(rootDir, { include, base: values.base });
         break;
       case "preview":
         await previewSite(rootDir, { port, include });

package/dist/vite/config.d.ts

@@ -4,5 +4,6 @@ export interface ConfigOptions {
     mode: 'development' | 'production';
     port?: number;
     include?: string[];
+    base?: string;
 }
 export declare function createViteConfig(options: ConfigOptions): Promise<InlineConfig>;

package/dist/vite/start.d.ts

@@ -4,6 +4,7 @@ export interface DevOptions {
 }
 export interface BuildOptions {
     include?: string[];
+    base?: string;
 }
 export declare function startDev(rootDir: string, options?: DevOptions): Promise<import("vite").ViteDevServer>;
 export declare function buildSite(rootDir: string, options?: BuildOptions): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prev-cli",
-  "version": "0.22.4",
+  "version": "0.24.0",
   "description": "Transform MDX directories into beautiful documentation websites",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,7 @@
   },
   "scripts": {
     "build": "bun build src/cli.ts --outdir dist --target node --packages external && tsc --emitDeclarationOnly",
+    "build:docs": "bun run build && bun ./dist/cli.js build",
     "dev": "tsc --watch",
     "test": "bun test src",
     "test:integration": "bun run build && bun test test/integration.test.ts",

package/src/theme/Preview.tsx

@@ -22,7 +22,11 @@ const DEVICE_WIDTHS: Record<DeviceMode, number | '100%'> = {
 
 export function Preview({ src, height = 400, title, mode = 'wasm', showHeader = false }: PreviewProps) {
   const [isFullscreen, setIsFullscreen] = useState(false)
-  const [deviceMode, setDeviceMode] = useState<DeviceMode>('desktop')
+  // Default to 'mobile' device mode on mobile viewports to match user's actual environment
+  const [deviceMode, setDeviceMode] = useState<DeviceMode>(() => {
+    if (typeof window === 'undefined') return 'desktop'
+    return window.innerWidth < 768 ? 'mobile' : 'desktop'
+  })
   const [customWidth, setCustomWidth] = useState<number | null>(null)
   const [showSlider, setShowSlider] = useState(false)
 
@@ -41,8 +45,11 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
   const isDev = import.meta.env?.DEV ?? false
   const effectiveMode = isDev ? mode : 'legacy'
 
+  // Get base URL for proper subpath deployment support
+  const baseUrl = (import.meta.env?.BASE_URL ?? '/').replace(/\/$/, '')
+
   // 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 previewUrl = effectiveMode === 'wasm' ? `/_preview-runtime?src=${src}` : `${baseUrl}/_preview/${src}/`
   const displayTitle = title || src
 
   // Calculate current width
@@ -194,95 +201,124 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
     </button>
   )
 
+  // Track viewport size for responsive layout
+  const [isMobileViewport, setIsMobileViewport] = useState(typeof window !== 'undefined' ? window.innerWidth < 480 : false)
+
+  useEffect(() => {
+    const handleResize = () => setIsMobileViewport(window.innerWidth < 480)
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [])
+
   // 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)"
-      >
-        <Icon name="mobile" size={16} />
-      </IconButton>
-
-      <IconButton
-        onClick={() => handleDeviceChange('tablet')}
-        active={deviceMode === 'tablet' && customWidth === null}
-        title="Tablet (768px)"
-      >
-        <Icon name="tablet" size={16} />
-      </IconButton>
-
-      <IconButton
-        onClick={() => handleDeviceChange('desktop')}
-        active={deviceMode === 'desktop' && customWidth === null}
-        title="Desktop (100%)"
-      >
-        <Icon name="desktop" size={16} />
-      </IconButton>
-
-      <div style={{ width: '1px', height: '16px', backgroundColor: 'var(--fd-border, #e4e4e7)', margin: '0 4px' }} />
-
-      {/* Width slider toggle */}
-      <div style={{ position: 'relative' }}>
+  // On mobile: simplified controls with just fullscreen
+  // On larger screens: full device controls
+  const DevTools = ({ compact = false }: { compact?: boolean }) => {
+    // Mobile viewport or compact mode: show minimal controls
+    if (isMobileViewport || compact) {
+      return (
+        <div style={{ display: 'flex', alignItems: 'center', gap: '2px' }}>
+          <IconButton
+            onClick={() => setIsFullscreen(!isFullscreen)}
+            active={isFullscreen}
+            title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+          >
+            <Icon name={isFullscreen ? 'minimize' : 'maximize'} size={16} />
+          </IconButton>
+        </div>
+      )
+    }
+
+    // Full controls for larger screens
+    return (
+      <div style={{ display: 'flex', alignItems: 'center', gap: '2px' }}>
         <IconButton
-          onClick={() => setShowSlider(!showSlider)}
-          active={showSlider || customWidth !== null}
-          title="Custom width"
+          onClick={() => handleDeviceChange('mobile')}
+          active={deviceMode === 'mobile' && customWidth === null}
+          title="Mobile (375px)"
         >
-          <Icon name="sliders" size={16} />
+          <Icon name="mobile" size={16} />
         </IconButton>
 
-        {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)' }}
-              >
-                <Icon name="x" size={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: '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>
+        <IconButton
+          onClick={() => handleDeviceChange('tablet')}
+          active={deviceMode === 'tablet' && customWidth === null}
+          title="Tablet (768px)"
+        >
+          <Icon name="tablet" size={16} />
+        </IconButton>
+
+        <IconButton
+          onClick={() => handleDeviceChange('desktop')}
+          active={deviceMode === 'desktop' && customWidth === null}
+          title="Desktop (100%)"
+        >
+          <Icon name="desktop" size={16} />
+        </IconButton>
+
+        <div style={{ width: '1px', height: '16px', backgroundColor: 'var(--fd-border, #e4e4e7)', margin: '0 4px' }} />
+
+        {/* Width slider toggle */}
+        <div style={{ position: 'relative' }}>
+          <IconButton
+            onClick={() => setShowSlider(!showSlider)}
+            active={showSlider || customWidth !== null}
+            title="Custom width"
+          >
+            <Icon name="sliders" size={16} />
+          </IconButton>
+
+          {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)' }}
+                >
+                  <Icon name="x" size={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: '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>
-        )}
-      </div>
+          )}
+        </div>
 
-      <IconButton
-        onClick={() => setIsFullscreen(!isFullscreen)}
-        active={isFullscreen}
-        title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
-      >
-        <Icon name={isFullscreen ? 'minimize' : 'maximize'} size={16} />
-      </IconButton>
-    </div>
-  )
+        <IconButton
+          onClick={() => setIsFullscreen(!isFullscreen)}
+          active={isFullscreen}
+          title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+        >
+          <Icon name={isFullscreen ? 'minimize' : 'maximize'} size={16} />
+        </IconButton>
+      </div>
+    )
+  }
 
   // Register DevTools in toolbar when on detail page (showHeader mode)
   useEffect(() => {
@@ -466,34 +502,45 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
       overflow: 'hidden',
       position: 'relative',
     }}>
-      {/* Compact header */}
+      {/* Compact header - responsive for mobile */}
       <div style={{
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'space-between',
-        padding: '8px 12px',
+        padding: isMobileViewport ? '6px 10px' : '8px 12px',
         backgroundColor: 'var(--fd-card, #fafafa)',
         borderBottom: '1px solid var(--fd-border, #e4e4e7)',
+        gap: '8px',
       }}>
-        <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
-          <span style={{ fontSize: '14px', fontWeight: 500, color: 'var(--fd-foreground, #52525b)' }}>
+        <div style={{ display: 'flex', alignItems: 'center', gap: '6px', minWidth: 0, flex: 1 }}>
+          <span style={{
+            fontSize: isMobileViewport ? '13px' : '14px',
+            fontWeight: 500,
+            color: 'var(--fd-foreground, #52525b)',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}>
             {displayTitle}
           </span>
           {mode === 'wasm' && buildStatus === 'building' && (
-            <Icon name="loader" size={14} style={{ color: 'var(--fd-primary, #3b82f6)', animation: 'spin 1s linear infinite' }} />
+            <Icon name="loader" size={14} style={{ color: 'var(--fd-primary, #3b82f6)', animation: 'spin 1s linear infinite', flexShrink: 0 }} />
           )}
           {mode === 'wasm' && buildStatus === 'error' && (
-            <span style={{ fontSize: '12px', color: '#ef4444' }}>Error</span>
+            <span style={{ fontSize: '12px', color: '#ef4444', flexShrink: 0 }}>Error</span>
           )}
         </div>
-        <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
-          {mode === 'wasm' && buildTime && (
+        <div style={{ display: 'flex', alignItems: 'center', gap: '6px', flexShrink: 0 }}>
+          {/* Hide build time and width on mobile to save space */}
+          {!isMobileViewport && mode === 'wasm' && buildTime && (
             <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)' }}>{buildTime}ms</span>
           )}
-          <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)' }}>
-            {currentWidth ? `${currentWidth}px` : '100%'}
-          </span>
-          <DevTools />
+          {!isMobileViewport && (
+            <span style={{ fontSize: '12px', color: 'var(--fd-muted-foreground, #a1a1aa)' }}>
+              {currentWidth ? `${currentWidth}px` : '100%'}
+            </span>
+          )}
+          <DevTools compact={isMobileViewport} />
         </div>
       </div>
 

package/src/theme/TOCPanel.css

@@ -120,8 +120,20 @@
   position: fixed;
   inset: 0;
   z-index: 9998;
-  background: rgba(0, 0, 0, 0.5);
-  backdrop-filter: blur(4px);
+  background: rgba(0, 0, 0, 0.4);
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
+  animation: fade-in-overlay 0.2s ease;
+}
+
+@keyframes fade-in-overlay {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes slide-up-sheet {
+  from { transform: translateY(100%); }
+  to { transform: translateY(0); }
 }
 
 .toc-overlay-content {
@@ -129,15 +141,31 @@
   bottom: 0;
   left: 0;
   right: 0;
-  max-height: 80vh;
+  max-height: 70vh;
   background: var(--fd-background);
-  border-radius: 1rem 1rem 0 0;
+  border-radius: 1.25rem 1.25rem 0 0;
   overflow: hidden;
+  box-shadow: 0 -4px 24px rgba(0, 0, 0, 0.12);
+  animation: slide-up-sheet 0.25s ease;
+  /* Bottom safe area for toolbar overlap prevention */
+  padding-bottom: calc(env(safe-area-inset-bottom, 0px) + 72px);
+}
+
+/* Bottom sheet drag indicator */
+.toc-overlay-content::before {
+  content: '';
+  display: block;
+  width: 36px;
+  height: 4px;
+  background: var(--fd-border);
+  border-radius: 2px;
+  margin: 8px auto;
 }
 
 .toc-overlay-content .toc-nav {
-  max-height: calc(80vh - 60px);
-  padding: 1rem;
+  max-height: calc(70vh - 120px);
+  padding: 0.5rem 1rem 1rem;
+  overscroll-behavior: contain;
 }
 
 @media (max-width: 768px) {

package/src/theme/Toolbar.css

@@ -11,12 +11,31 @@
   box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
   cursor: grab;
   user-select: none;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
 }
 
 .prev-toolbar:active {
   cursor: grabbing;
 }
 
+/* Mobile: center toolbar at bottom with safe area */
+@media (max-width: 768px) {
+  .prev-toolbar {
+    left: 50% !important;
+    bottom: calc(env(safe-area-inset-bottom, 0px) + 16px) !important;
+    top: auto !important;
+    transform: translateX(-50%);
+    cursor: default;
+    padding: 0.5rem 0.75rem;
+    gap: 0.375rem;
+    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
+  }
+
+  .prev-toolbar:active {
+    cursor: default;
+  }
+}
+
 .toolbar-btn {
   display: flex;
   align-items: center;
@@ -30,6 +49,7 @@
   cursor: pointer;
   transition: all 0.15s ease;
   text-decoration: none;
+  -webkit-tap-highlight-color: transparent;
 }
 
 .toolbar-btn:hover {
@@ -37,11 +57,23 @@
   color: var(--fd-foreground);
 }
 
+.toolbar-btn:active {
+  transform: scale(0.92);
+}
+
 .toolbar-btn.active {
   background: var(--fd-accent);
   color: var(--fd-accent-foreground);
 }
 
+/* Mobile: larger touch targets */
+@media (max-width: 768px) {
+  .toolbar-btn {
+    width: 40px;
+    height: 40px;
+  }
+}
+
 .toolbar-devtools-slot {
   display: flex;
   align-items: center;
@@ -95,4 +127,16 @@
   .toolbar-btn.desktop-only {
     display: none;
   }
+
+  /* Simplify devtools on mobile - hide separator and some controls */
+  .toolbar-devtools-slot {
+    gap: 0.25rem;
+    margin-left: 0.375rem;
+    padding-left: 0.375rem;
+  }
+
+  /* Hide custom width slider button on mobile */
+  .toolbar-devtools-slot > div:has(button[title="Custom width"]) {
+    display: none;
+  }
 }

package/src/theme/Toolbar.tsx

@@ -19,20 +19,30 @@ interface ToolbarProps {
 export function Toolbar({ tree, onThemeToggle, onWidthToggle, isDark, isFullWidth, onTocToggle, tocOpen }: ToolbarProps) {
   const [position, setPosition] = useState({ x: 20, y: typeof window !== 'undefined' ? window.innerHeight - 80 : 600 })
   const [dragging, setDragging] = useState(false)
+  const [isMobile, setIsMobile] = useState(typeof window !== 'undefined' ? window.innerWidth <= 768 : false)
   const dragStart = useRef({ x: 0, y: 0 })
   const toolbarRef = useRef<HTMLDivElement>(null)
   const location = useLocation()
   const isOnPreviews = location.pathname.startsWith('/previews')
   const { devToolsContent } = useDevTools()
 
+  // Track mobile state
+  useEffect(() => {
+    const handleResize = () => setIsMobile(window.innerWidth <= 768)
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [])
+
   const handleMouseDown = (e: React.MouseEvent) => {
+    // Disable dragging on mobile
+    if (isMobile) return
     if ((e.target as HTMLElement).closest('button, a')) return
     setDragging(true)
     dragStart.current = { x: e.clientX - position.x, y: e.clientY - position.y }
   }
 
   useEffect(() => {
-    if (!dragging) return
+    if (!dragging || isMobile) return
 
     const handleMouseMove = (e: MouseEvent) => {
       setPosition({
@@ -49,13 +59,13 @@ export function Toolbar({ tree, onThemeToggle, onWidthToggle, isDark, isFullWidt
       document.removeEventListener('mousemove', handleMouseMove)
       document.removeEventListener('mouseup', handleMouseUp)
     }
-  }, [dragging])
+  }, [dragging, isMobile])
 
   return (
     <div
       ref={toolbarRef}
       className="prev-toolbar"
-      style={{ left: position.x, top: position.y }}
+      style={isMobile ? undefined : { left: position.x, top: position.y }}
       onMouseDown={handleMouseDown}
     >
       <button

package/src/theme/entry.tsx

@@ -99,15 +99,15 @@ function PreviewsCatalog() {
         <h1 style={{ fontSize: '24px', fontWeight: 'bold', marginBottom: '16px' }}>
           No Previews Found
         </h1>
-        <p style={{ color: '#666', marginBottom: '24px' }}>
+        <p style={{ color: 'var(--fd-muted-foreground)', marginBottom: '24px' }}>
           Create your first preview with:
         </p>
         <code style={{
           display: 'inline-block',
           padding: '12px 20px',
-          backgroundColor: '#f4f4f5',
+          backgroundColor: 'var(--fd-muted)',
           borderRadius: '8px',
-          fontFamily: 'monospace',
+          fontFamily: 'var(--fd-font-mono)',
         }}>
           prev create my-demo
         </code>
@@ -116,37 +116,33 @@ function PreviewsCatalog() {
   }
 
   return (
-    <div style={{ padding: '20px' }}>
-      <div style={{ marginBottom: '32px' }}>
+    <div className="previews-catalog">
+      <div style={{ marginBottom: '24px' }}>
         <h1 style={{ fontSize: '28px', fontWeight: 'bold', marginBottom: '8px' }}>
           Previews
         </h1>
-        <p style={{ color: '#666' }}>
+        <p style={{ color: 'var(--fd-muted-foreground)', margin: 0 }}>
           {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(320px, 1fr))',
-        gap: '20px',
-      }}>
+      <div className="previews-grid">
         {previews.map((preview: { name: string; route: string }) => (
           <PreviewCard key={preview.name} name={preview.name} />
         ))}
       </div>
 
       <div style={{
-        marginTop: '40px',
-        padding: '16px',
+        marginTop: '32px',
+        padding: '14px 16px',
         backgroundColor: 'var(--fd-muted)',
         border: '1px solid var(--fd-border)',
-        borderRadius: '8px',
+        borderRadius: '10px',
       }}>
         <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: 'var(--fd-accent)', padding: '2px 6px', borderRadius: '4px' }}>
+          <strong style={{ color: 'var(--fd-foreground)' }}>Tip:</strong> Embed any preview in your MDX docs with{' '}
+          <code style={{ backgroundColor: 'var(--fd-accent)', padding: '2px 6px', borderRadius: '4px', fontFamily: 'var(--fd-font-mono)' }}>
             {'<Preview src="name" />'}
           </code>
         </p>
@@ -161,10 +157,23 @@ 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)
+  const [loadError, setLoadError] = 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}/`
+  const baseUrl = (import.meta.env?.BASE_URL ?? '/').replace(/\/$/, '')
+  const previewUrl = isDev ? `/_preview-runtime?src=${name}` : `${baseUrl}/_preview/${name}/`
+
+  // Timeout for loading - show placeholder if too slow
+  React.useEffect(() => {
+    const timeout = setTimeout(() => {
+      if (!isLoaded) {
+        setLoadError(true)
+      }
+    }, 5000) // 5 second timeout
+
+    return () => clearTimeout(timeout)
+  }, [isLoaded])
 
   // Set up WASM preview communication for thumbnail (dev mode only)
   React.useEffect(() => {
@@ -173,6 +182,7 @@ function PreviewCard({ name }: { name: string }) {
       const iframe = iframeRef.current
       if (iframe) {
         iframe.onload = () => setIsLoaded(true)
+        iframe.onerror = () => setLoadError(true)
       }
       return
     }
@@ -194,13 +204,17 @@ function PreviewCard({ name }: { name: string }) {
             iframe.contentWindow?.postMessage({ type: 'init', config } as PreviewMessage, '*')
           })
           .catch(() => {
-            // Silently fail for thumbnails
+            setLoadError(true)
           })
       }
 
       if (msg.type === 'built') {
         setIsLoaded(true)
       }
+
+      if (msg.type === 'error') {
+        setLoadError(true)
+      }
     }
 
     window.addEventListener('message', handleMessage)
@@ -211,87 +225,38 @@ function PreviewCard({ name }: { name: string }) {
   }, [name, isDev])
 
   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 = ''
-      }}
-    >
+    <Link to={`/previews/${name}`} className="preview-card">
       {/* Thumbnail preview */}
-      <div style={{
-        height: '180px',
-        overflow: 'hidden',
-        position: 'relative',
-        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 className="preview-card-thumbnail">
+        {/* Loading state */}
+        {!isLoaded && !loadError && (
+          <div className="preview-card-loading">
+            <div className="preview-card-spinner" />
+          </div>
+        )}
+        {/* Error/timeout placeholder */}
+        {loadError && (
+          <div className="preview-card-placeholder">
+            <svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+              <rect x="3" y="3" width="18" height="18" rx="2" />
+              <path d="M9 9l6 6m0-6l-6 6" />
+            </svg>
+            <span>Preview</span>
           </div>
         )}
         <iframe
           ref={iframeRef}
           src={previewUrl}
-          style={{
-            border: 'none',
-            transform: 'scale(0.5)',
-            transformOrigin: 'top left',
-            width: '200%',
-            height: '200%',
-            opacity: isLoaded ? 1 : 0,
-            transition: 'opacity 0.3s',
-          }}
+          className="preview-card-iframe"
+          style={{ opacity: isLoaded && !loadError ? 1 : 0 }}
           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 className="preview-card-footer">
+        <h3 className="preview-card-title">{name}</h3>
+        <code className="preview-card-path">previews/{name}/</code>
       </div>
     </Link>
   )
@@ -408,8 +373,12 @@ const routeTree = rootRoute.addChildren([
   ...(indexRedirectRoute ? [indexRedirectRoute] : []),
   ...pageRoutes,
 ])
+// Get base path for subpath deployments (e.g., GitHub Pages)
+const basepath = (import.meta.env?.BASE_URL ?? '/').replace(/\/$/, '') || '/'
+
 const router = createRouter({
   routeTree,
+  basepath,
   defaultNotFoundComponent: NotFoundPage,
 })
 

package/src/theme/mdx-components.tsx

@@ -1,5 +1,111 @@
+import React from 'react'
+import { Link } from '@tanstack/react-router'
 import { Preview } from './Preview'
+import { pages } from 'virtual:prev-pages'
+
+// Get valid routes from pages
+const validRoutes = new Set(pages.map((p: { route: string }) => p.route))
+
+// Also add /previews routes
+validRoutes.add('/previews')
+
+// Check if a path is an internal link
+function isInternalLink(href: string): boolean {
+  if (!href) return false
+  // External links start with http://, https://, mailto:, tel:, etc.
+  if (/^(https?:|mailto:|tel:|#)/.test(href)) return false
+  // Relative or absolute internal paths
+  return href.startsWith('/') || !href.includes(':')
+}
+
+// Check if an internal route exists
+function routeExists(href: string): boolean {
+  if (!href) return true
+  // Remove hash and query string
+  const path = href.split(/[?#]/)[0]
+  // Check exact match or if it's a valid preview route
+  if (validRoutes.has(path)) return true
+  // Check if it starts with /previews/ (dynamic preview routes)
+  if (path.startsWith('/previews/')) return true
+  return false
+}
+
+// Custom link component that validates internal links and uses router
+function MdxLink({ href, children, ...props }: React.AnchorHTMLAttributes<HTMLAnchorElement>) {
+  const isInternal = isInternalLink(href || '')
+  const isDev = import.meta.env?.DEV ?? false
+
+  // For internal links, use TanStack Router's Link
+  if (isInternal && href) {
+    const exists = routeExists(href)
+
+    // In dev mode, show warning for dead links
+    if (isDev && !exists) {
+      return (
+        <span
+          className="dead-link"
+          title={`Dead link: "${href}" does not match any known route`}
+          {...props}
+        >
+          {children}
+          <span className="dead-link-icon" aria-label="Dead link">⚠️</span>
+        </span>
+      )
+    }
+
+    return (
+      <Link to={href} {...props}>
+        {children}
+      </Link>
+    )
+  }
+
+  // External links open in new tab
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      {...props}
+    >
+      {children}
+    </a>
+  )
+}
+
+// Responsive table wrapper for horizontal scrolling on mobile
+function MdxTable({ children, ...props }: React.TableHTMLAttributes<HTMLTableElement>) {
+  const wrapperRef = React.useRef<HTMLDivElement>(null)
+
+  React.useEffect(() => {
+    const wrapper = wrapperRef.current
+    if (!wrapper) return
+
+    // Check if table overflows and add class for scroll indicator
+    const checkOverflow = () => {
+      const hasOverflow = wrapper.scrollWidth > wrapper.clientWidth
+      wrapper.classList.toggle('has-scroll', hasOverflow && wrapper.scrollLeft < wrapper.scrollWidth - wrapper.clientWidth - 1)
+    }
+
+    checkOverflow()
+    wrapper.addEventListener('scroll', checkOverflow)
+    window.addEventListener('resize', checkOverflow)
+
+    return () => {
+      wrapper.removeEventListener('scroll', checkOverflow)
+      window.removeEventListener('resize', checkOverflow)
+    }
+  }, [])
+
+  return (
+    <div ref={wrapperRef} className="table-wrapper">
+      <table {...props}>{children}</table>
+    </div>
+  )
+}
 
 export const mdxComponents = {
   Preview,
+  a: MdxLink,
+  table: MdxTable,
 }

package/src/theme/styles.css

@@ -214,6 +214,27 @@ body {
   padding-bottom: 3rem !important;
 }
 
+/* Mobile: reduce content padding for better use of screen space */
+@media (max-width: 640px) {
+  .prev-content {
+    padding-left: 1rem !important;
+    padding-right: 1rem !important;
+    font-size: 0.9375rem;
+  }
+
+  .prev-content h1 {
+    font-size: 1.75rem;
+  }
+
+  .prev-content h2 {
+    font-size: 1.25rem;
+  }
+
+  .prev-content h3 {
+    font-size: 1.125rem;
+  }
+}
+
 /* Heading styles with better spacing */
 .prev-content h1 {
   font-size: 2.25rem;
@@ -340,14 +361,57 @@ body {
   color: var(--fd-foreground);
 }
 
-/* Table styling */
-.prev-content table {
+/* Table styling - responsive with horizontal scroll on mobile */
+.prev-content .table-wrapper {
   width: 100%;
   margin: 1.75rem 0;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+/* Scroll indicator gradient for tables on mobile */
+@media (max-width: 640px) {
+  .prev-content .table-wrapper {
+    position: relative;
+  }
+
+  .prev-content .table-wrapper::after {
+    content: '';
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    width: 24px;
+    background: linear-gradient(to right, transparent, var(--fd-background));
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity 0.2s ease;
+  }
+
+  .prev-content .table-wrapper.has-scroll::after {
+    opacity: 1;
+  }
+}
+
+.prev-content table {
+  width: 100%;
+  min-width: max-content;
   border-collapse: collapse;
   font-size: 0.925rem;
 }
 
+/* Mobile: smaller table font and padding */
+@media (max-width: 640px) {
+  .prev-content table {
+    font-size: 0.85rem;
+  }
+
+  .prev-content th,
+  .prev-content td {
+    padding: 0.625rem 0.75rem;
+  }
+}
+
 .prev-content thead {
   border-bottom: 2px solid var(--fd-border);
 }
@@ -357,6 +421,7 @@ body {
   text-align: left;
   font-weight: 600;
   background: var(--fd-muted);
+  white-space: nowrap;
 }
 
 .prev-content th:first-child {
@@ -567,3 +632,185 @@ body {
     box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08);
   }
 }
+
+/* ===========================================
+   Previews Catalog - Mobile-First Grid
+   =========================================== */
+
+.previews-catalog {
+  padding: 16px;
+}
+
+@media (min-width: 640px) {
+  .previews-catalog {
+    padding: 20px;
+  }
+}
+
+.previews-grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 16px;
+}
+
+@media (min-width: 480px) {
+  .previews-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (min-width: 768px) {
+  .previews-grid {
+    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+    gap: 20px;
+  }
+}
+
+/* Preview card enhancements */
+.previews-grid a {
+  display: block;
+  border: 1px solid var(--fd-border);
+  border-radius: 12px;
+  overflow: hidden;
+  background-color: var(--fd-background);
+  text-decoration: none;
+  color: inherit;
+  transition: box-shadow 0.2s ease, transform 0.2s ease, border-color 0.2s ease;
+}
+
+.previews-grid a:hover {
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);
+  transform: translateY(-2px);
+  border-color: var(--fd-primary);
+}
+
+.previews-grid a:active {
+  transform: translateY(0);
+}
+
+/* Preview Card Component Styles */
+.preview-card-thumbnail {
+  height: 140px;
+  overflow: hidden;
+  position: relative;
+  background-color: var(--fd-muted);
+  pointer-events: none;
+}
+
+@media (min-width: 480px) {
+  .preview-card-thumbnail {
+    height: 160px;
+  }
+}
+
+@media (min-width: 768px) {
+  .preview-card-thumbnail {
+    height: 180px;
+  }
+}
+
+.preview-card-loading {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--fd-muted);
+  z-index: 1;
+}
+
+.preview-card-spinner {
+  width: 24px;
+  height: 24px;
+  border: 2px solid var(--fd-border);
+  border-top-color: var(--fd-primary);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+.preview-card-placeholder {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  background-color: var(--fd-muted);
+  color: var(--fd-muted-foreground);
+  z-index: 1;
+}
+
+.preview-card-placeholder span {
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.preview-card-iframe {
+  border: none;
+  transform: scale(0.5);
+  transform-origin: top left;
+  width: 200%;
+  height: 200%;
+  transition: opacity 0.3s ease;
+}
+
+.preview-card-footer {
+  padding: 12px 14px;
+  border-top: 1px solid var(--fd-border);
+  background-color: var(--fd-card);
+}
+
+.preview-card-title {
+  font-size: 14px;
+  font-weight: 600;
+  margin: 0 0 2px 0;
+  color: var(--fd-foreground);
+}
+
+.preview-card-path {
+  font-size: 11px;
+  color: var(--fd-muted-foreground);
+  font-family: var(--fd-font-mono);
+}
+
+/* ===========================================
+   Dead Link Warning (Dev Mode Only)
+   =========================================== */
+
+.dead-link {
+  color: #dc2626;
+  text-decoration: line-through;
+  text-decoration-color: #dc2626;
+  cursor: not-allowed;
+  position: relative;
+}
+
+.dead-link-icon {
+  font-size: 0.75em;
+  margin-left: 0.25em;
+  vertical-align: super;
+}
+
+/* Tooltip on hover */
+.dead-link::after {
+  content: attr(title);
+  position: absolute;
+  bottom: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  padding: 6px 10px;
+  background: #1f2937;
+  color: #fff;
+  font-size: 12px;
+  border-radius: 6px;
+  white-space: nowrap;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 100;
+}
+
+.dead-link:hover::after {
+  opacity: 1;
+}