prev-cli 0.22.3 → 0.23.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
-import path9 from "path";
+import path10 from "path";
 import { existsSync as existsSync7, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4, rmSync as rmSync3, readFileSync as readFileSync5 } from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
@@ -15,7 +15,7 @@ import react from "@vitejs/plugin-react";
 import mdx from "@mdx-js/rollup";
 import remarkGfm from "remark-gfm";
 import rehypeHighlight from "rehype-highlight";
-import path7 from "path";
+import path8 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
 
@@ -70,6 +70,9 @@ async function ensureCacheDir(rootDir) {
   return cacheDir;
 }
 
+// src/vite/plugins/pages-plugin.ts
+import path3 from "path";
+
 // src/vite/pages.ts
 import fg from "fast-glob";
 import { readFile } from "fs/promises";
@@ -127,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;
@@ -254,45 +262,82 @@ function buildSidebarTree(pages) {
 // src/vite/plugins/pages-plugin.ts
 var VIRTUAL_MODULE_ID = "virtual:prev-pages";
 var RESOLVED_VIRTUAL_MODULE_ID = "\x00" + VIRTUAL_MODULE_ID;
+var VIRTUAL_MODULES_ID = "virtual:prev-page-modules";
+var RESOLVED_VIRTUAL_MODULES_ID = "\x00" + VIRTUAL_MODULES_ID;
 function pagesPlugin(rootDir, options = {}) {
   const { include } = options;
+  let cachedPages = null;
+  async function getPages() {
+    if (!cachedPages) {
+      cachedPages = await scanPages(rootDir, { include });
+    }
+    return cachedPages;
+  }
   return {
     name: "prev-pages",
     resolveId(id) {
       if (id === VIRTUAL_MODULE_ID) {
         return RESOLVED_VIRTUAL_MODULE_ID;
       }
+      if (id === VIRTUAL_MODULES_ID) {
+        return RESOLVED_VIRTUAL_MODULES_ID;
+      }
     },
     async load(id) {
       if (id === RESOLVED_VIRTUAL_MODULE_ID) {
-        const pages = await scanPages(rootDir, { include });
+        const pages = await getPages();
         const sidebar = buildSidebarTree(pages);
         return `
           export const pages = ${JSON.stringify(pages)};
           export const sidebar = ${JSON.stringify(sidebar)};
         `;
       }
+      if (id === RESOLVED_VIRTUAL_MODULES_ID) {
+        const pages = await getPages();
+        const imports = pages.map((page, i) => {
+          const absolutePath = path3.join(rootDir, page.file);
+          return `import * as _page${i} from ${JSON.stringify(absolutePath)};`;
+        }).join(`
+`);
+        const entries = pages.map((page, i) => {
+          return `  ${JSON.stringify("/" + page.file)}: _page${i}`;
+        }).join(`,
+`);
+        return `${imports}
+
+export const pageModules = {
+${entries}
+};`;
+      }
     },
     handleHotUpdate({ file, server }) {
       if (file.endsWith(".mdx") || file.endsWith(".md")) {
+        cachedPages = null;
         const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
+        const modulesMod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULES_ID);
+        const mods = [];
         if (mod) {
           server.moduleGraph.invalidateModule(mod);
-          return [mod];
+          mods.push(mod);
+        }
+        if (modulesMod) {
+          server.moduleGraph.invalidateModule(modulesMod);
+          mods.push(modulesMod);
         }
+        return mods.length > 0 ? mods : undefined;
       }
     }
   };
 }
 
 // src/vite/plugins/entry-plugin.ts
-import path3 from "path";
+import path4 from "path";
 import { fileURLToPath } from "url";
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from "fs";
 function findCliRoot() {
-  let dir = path3.dirname(fileURLToPath(import.meta.url));
+  let dir = path4.dirname(fileURLToPath(import.meta.url));
   for (let i = 0;i < 10; i++) {
-    const pkgPath = path3.join(dir, "package.json");
+    const pkgPath = path4.join(dir, "package.json");
     if (existsSync(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
@@ -301,15 +346,15 @@ function findCliRoot() {
         }
       } catch {}
     }
-    const parent = path3.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir)
       break;
     dir = parent;
   }
-  return path3.dirname(path3.dirname(fileURLToPath(import.meta.url)));
+  return path4.dirname(path4.dirname(fileURLToPath(import.meta.url)));
 }
 var cliRoot = findCliRoot();
-var srcRoot = path3.join(cliRoot, "src");
+var srcRoot = path4.join(cliRoot, "src");
 function getHtml(entryPath, forBuild = false) {
   const scriptSrc = forBuild ? entryPath : `/@fs${entryPath}`;
   return `<!DOCTYPE html>
@@ -332,13 +377,13 @@ function getHtml(entryPath, forBuild = false) {
 </html>`;
 }
 function entryPlugin(rootDir) {
-  const entryPath = path3.join(srcRoot, "theme/entry.tsx");
+  const entryPath = path4.join(srcRoot, "theme/entry.tsx");
   let tempHtmlPath = null;
   return {
     name: "prev-entry",
     config(config, { command }) {
       if (command === "build" && rootDir) {
-        tempHtmlPath = path3.join(rootDir, "index.html");
+        tempHtmlPath = path4.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;
@@ -385,10 +430,10 @@ function entryPlugin(rootDir) {
 
 // src/vite/previews.ts
 import fg2 from "fast-glob";
-import path4 from "path";
+import path5 from "path";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 async function scanPreviews(rootDir) {
-  const previewsDir = path4.join(rootDir, "previews");
+  const previewsDir = path5.join(rootDir, "previews");
   if (!existsSync2(previewsDir)) {
     return [];
   }
@@ -398,17 +443,17 @@ async function scanPreviews(rootDir) {
   });
   const previewDirs = new Map;
   for (const file of entryFiles) {
-    const dir = path4.dirname(file);
+    const dir = path5.dirname(file);
     if (!previewDirs.has(dir)) {
       previewDirs.set(dir, file);
     }
   }
   return Array.from(previewDirs.entries()).map(([dir, file]) => {
-    const name = dir === "." ? path4.basename(previewsDir) : dir;
+    const name = dir === "." ? path5.basename(previewsDir) : dir;
     return {
       name,
       route: `/_preview/${name}`,
-      htmlPath: path4.join(previewsDir, file)
+      htmlPath: path5.join(previewsDir, file)
     };
   });
 }
@@ -418,8 +463,8 @@ async function scanPreviewFiles(previewDir) {
     ignore: ["node_modules/**", "dist/**"]
   });
   return files.map((file) => {
-    const content = readFileSync2(path4.join(previewDir, file), "utf-8");
-    const ext = path4.extname(file).slice(1);
+    const content = readFileSync2(path5.join(previewDir, file), "utf-8");
+    const ext = path5.extname(file).slice(1);
     return {
       path: file,
       content,
@@ -563,7 +608,7 @@ async function buildPreviewHtml(config) {
 
 // src/vite/plugins/previews-plugin.ts
 import { existsSync as existsSync3, mkdirSync, rmSync, writeFileSync as writeFileSync2 } from "fs";
-import path5 from "path";
+import path6 from "path";
 var VIRTUAL_MODULE_ID2 = "virtual:prev-previews";
 var RESOLVED_VIRTUAL_MODULE_ID2 = "\x00" + VIRTUAL_MODULE_ID2;
 function previewsPlugin(rootDir) {
@@ -596,10 +641,10 @@ function previewsPlugin(rootDir) {
     async closeBundle() {
       if (!isBuild)
         return;
-      const distDir = path5.join(rootDir, "dist");
-      const targetDir = path5.join(distDir, "_preview");
-      const previewsDir = path5.join(rootDir, "previews");
-      const oldPreviewsDir = path5.join(distDir, "previews");
+      const distDir = path6.join(rootDir, "dist");
+      const targetDir = path6.join(distDir, "_preview");
+      const previewsDir = path6.join(rootDir, "previews");
+      const oldPreviewsDir = path6.join(distDir, "previews");
       if (existsSync3(oldPreviewsDir)) {
         rmSync(oldPreviewsDir, { recursive: true });
       }
@@ -612,7 +657,7 @@ function previewsPlugin(rootDir) {
       console.log(`
   Building ${previews.length} preview(s)...`);
       for (const preview of previews) {
-        const previewDir = path5.join(previewsDir, preview.name);
+        const previewDir = path6.join(previewsDir, preview.name);
         try {
           const config = await buildPreviewConfig(previewDir);
           const result = await buildPreviewHtml(config);
@@ -620,9 +665,9 @@ function previewsPlugin(rootDir) {
             console.error(`    ✗ ${preview.name}: ${result.error}`);
             continue;
           }
-          const outputDir = path5.join(targetDir, preview.name);
+          const outputDir = path6.join(targetDir, preview.name);
           mkdirSync(outputDir, { recursive: true });
-          writeFileSync2(path5.join(outputDir, "index.html"), result.html);
+          writeFileSync2(path6.join(outputDir, "index.html"), result.html);
           console.log(`    ✓ ${preview.name}`);
         } catch (err) {
           console.error(`    ✗ ${preview.name}: ${err}`);
@@ -693,11 +738,11 @@ function validateConfig(raw) {
 }
 // src/config/loader.ts
 import { readFileSync as readFileSync3, existsSync as existsSync4, writeFileSync as writeFileSync3 } from "fs";
-import path6 from "path";
+import path7 from "path";
 import yaml from "js-yaml";
 function findConfigFile(rootDir) {
-  const yamlPath = path6.join(rootDir, ".prev.yaml");
-  const ymlPath = path6.join(rootDir, ".prev.yml");
+  const yamlPath = path7.join(rootDir, ".prev.yaml");
+  const ymlPath = path7.join(rootDir, ".prev.yml");
   if (existsSync4(yamlPath))
     return yamlPath;
   if (existsSync4(ymlPath))
@@ -719,7 +764,7 @@ function loadConfig(rootDir) {
   }
 }
 function saveConfig(rootDir, config) {
-  const configPath = findConfigFile(rootDir) || path6.join(rootDir, ".prev.yaml");
+  const configPath = findConfigFile(rootDir) || path7.join(rootDir, ".prev.yaml");
   const content = yaml.dump(config, {
     indent: 2,
     lineWidth: -1,
@@ -788,9 +833,9 @@ function createFriendlyLogger() {
   };
 }
 function findCliRoot2() {
-  let dir = path7.dirname(fileURLToPath2(import.meta.url));
+  let dir = path8.dirname(fileURLToPath2(import.meta.url));
   for (let i = 0;i < 10; i++) {
-    const pkgPath = path7.join(dir, "package.json");
+    const pkgPath = path8.join(dir, "package.json");
     if (existsSync5(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
@@ -799,24 +844,24 @@ function findCliRoot2() {
         }
       } catch {}
     }
-    const parent = path7.dirname(dir);
+    const parent = path8.dirname(dir);
     if (parent === dir)
       break;
     dir = parent;
   }
-  return path7.dirname(path7.dirname(fileURLToPath2(import.meta.url)));
+  return path8.dirname(path8.dirname(fileURLToPath2(import.meta.url)));
 }
 function findNodeModules(cliRoot2) {
-  const localNodeModules = path7.join(cliRoot2, "node_modules");
-  if (existsSync5(path7.join(localNodeModules, "react"))) {
+  const localNodeModules = path8.join(cliRoot2, "node_modules");
+  if (existsSync5(path8.join(localNodeModules, "react"))) {
     return localNodeModules;
   }
   let dir = cliRoot2;
   for (let i = 0;i < 10; i++) {
-    const parent = path7.dirname(dir);
+    const parent = path8.dirname(dir);
     if (parent === dir)
       break;
-    if (path7.basename(parent) === "node_modules" && existsSync5(path7.join(parent, "react"))) {
+    if (path8.basename(parent) === "node_modules" && existsSync5(path8.join(parent, "react"))) {
       return parent;
     }
     dir = parent;
@@ -825,15 +870,16 @@ function findNodeModules(cliRoot2) {
 }
 var cliRoot2 = findCliRoot2();
 var cliNodeModules = findNodeModules(cliRoot2);
-var srcRoot2 = path7.join(cliRoot2, "src");
+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: [
@@ -883,7 +929,7 @@ async function createViteConfig(options) {
               if (urlPath.startsWith("/__") || urlPath.startsWith("/@") || urlPath.startsWith("/node_modules") || urlPath.includes(".")) {
                 return next();
               }
-              const indexPath = path7.join(srcRoot2, "theme/index.html");
+              const indexPath = path8.join(srcRoot2, "theme/index.html");
               if (existsSync5(indexPath)) {
                 server.transformIndexHtml(req.url, readFileSync4(indexPath, "utf-8")).then((html) => {
                   res.setHeader("Content-Type", "text/html");
@@ -901,8 +947,8 @@ async function createViteConfig(options) {
         resolveId(id) {
           if (id.startsWith("/_preview/")) {
             const relativePath = id.slice("/_preview/".length);
-            const previewsDir = path7.join(rootDir, "previews");
-            const resolved = path7.resolve(previewsDir, relativePath);
+            const previewsDir = path8.join(rootDir, "previews");
+            const resolved = path8.resolve(previewsDir, relativePath);
             if (resolved.startsWith(previewsDir)) {
               return resolved;
             }
@@ -912,7 +958,7 @@ async function createViteConfig(options) {
           server.middlewares.use(async (req, res, next) => {
             const urlPath = req.url?.split("?")[0] || "";
             if (urlPath === "/_preview-runtime") {
-              const templatePath = path7.join(srcRoot2, "preview-runtime/template.html");
+              const templatePath = path8.join(srcRoot2, "preview-runtime/template.html");
               if (existsSync5(templatePath)) {
                 const html = readFileSync4(templatePath, "utf-8");
                 res.setHeader("Content-Type", "text/html");
@@ -922,8 +968,8 @@ async function createViteConfig(options) {
             }
             if (urlPath.startsWith("/_preview-config/")) {
               const previewName = decodeURIComponent(urlPath.slice("/_preview-config/".length));
-              const previewsDir = path7.join(rootDir, "previews");
-              const previewDir = path7.resolve(previewsDir, previewName);
+              const previewsDir = path8.join(rootDir, "previews");
+              const previewDir = path8.resolve(previewsDir, previewName);
               if (!previewDir.startsWith(previewsDir)) {
                 res.statusCode = 403;
                 res.end("Forbidden");
@@ -944,11 +990,11 @@ async function createViteConfig(options) {
               }
             }
             if (urlPath.startsWith("/_preview/")) {
-              const isHtmlRequest = !path7.extname(urlPath) || urlPath.endsWith("/");
+              const isHtmlRequest = !path8.extname(urlPath) || urlPath.endsWith("/");
               if (isHtmlRequest) {
                 const previewName = decodeURIComponent(urlPath.slice("/_preview/".length).replace(/\/$/, ""));
-                const previewsDir = path7.join(rootDir, "previews");
-                const htmlPath = path7.resolve(previewsDir, previewName, "index.html");
+                const previewsDir = path8.join(rootDir, "previews");
+                const htmlPath = path8.resolve(previewsDir, previewName, "index.html");
                 if (!htmlPath.startsWith(previewsDir)) {
                   return next();
                 }
@@ -975,15 +1021,15 @@ async function createViteConfig(options) {
     ],
     resolve: {
       alias: {
-        "@prev/ui": path7.join(srcRoot2, "ui"),
-        "@prev/theme": path7.join(srcRoot2, "theme"),
-        react: path7.join(cliNodeModules, "react"),
-        "react-dom": path7.join(cliNodeModules, "react-dom"),
-        "@tanstack/react-router": path7.join(cliNodeModules, "@tanstack/react-router"),
-        "@mdx-js/react": path7.join(cliNodeModules, "@mdx-js/react"),
-        mermaid: path7.join(cliNodeModules, "mermaid"),
-        dayjs: path7.join(cliNodeModules, "dayjs"),
-        "@terrastruct/d2": path7.join(cliNodeModules, "@terrastruct/d2")
+        "@prev/ui": path8.join(srcRoot2, "ui"),
+        "@prev/theme": path8.join(srcRoot2, "theme"),
+        react: path8.join(cliNodeModules, "react"),
+        "react-dom": path8.join(cliNodeModules, "react-dom"),
+        "@tanstack/react-router": path8.join(cliNodeModules, "@tanstack/react-router"),
+        "@mdx-js/react": path8.join(cliNodeModules, "@mdx-js/react"),
+        mermaid: path8.join(cliNodeModules, "mermaid"),
+        dayjs: path8.join(cliNodeModules, "dayjs"),
+        "@terrastruct/d2": path8.join(cliNodeModules, "@terrastruct/d2")
       },
       dedupe: [
         "react",
@@ -1008,6 +1054,7 @@ async function createViteConfig(options) {
         "virtual:prev-config",
         "virtual:prev-previews",
         "virtual:prev-pages",
+        "virtual:prev-page-modules",
         "@prev/theme"
       ]
     },
@@ -1022,8 +1069,8 @@ async function createViteConfig(options) {
       },
       warmup: {
         clientFiles: [
-          path7.join(srcRoot2, "theme/entry.tsx"),
-          path7.join(srcRoot2, "theme/styles.css")
+          path8.join(srcRoot2, "theme/entry.tsx"),
+          path8.join(srcRoot2, "theme/styles.css")
         ]
       }
     },
@@ -1032,12 +1079,12 @@ async function createViteConfig(options) {
       strictPort: false
     },
     build: {
-      outDir: path7.join(rootDir, "dist"),
+      outDir: path8.join(rootDir, "dist"),
       reportCompressedSize: false,
       chunkSizeWarningLimit: 1e4,
       rollupOptions: {
         input: {
-          main: path7.join(srcRoot2, "theme/index.html")
+          main: path8.join(srcRoot2, "theme/index.html")
         }
       }
     }
@@ -1077,8 +1124,8 @@ 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 path8 from "path";
+import { existsSync as existsSync6, rmSync as rmSync2, copyFileSync } from "fs";
+import path9 from "path";
 function printWelcome(type) {
   console.log();
   console.log("  ✨ prev");
@@ -1111,8 +1158,8 @@ function openBrowser(url) {
   console.log(`  ↗ Opened ${url}`);
 }
 function clearCache(rootDir) {
-  const viteCacheDir = path8.join(rootDir, ".vite");
-  const nodeModulesVite = path8.join(rootDir, "node_modules", ".vite");
+  const viteCacheDir = path9.join(rootDir, ".vite");
+  const nodeModulesVite = path9.join(rootDir, "node_modules", ".vite");
   let cleared = 0;
   if (existsSync6(viteCacheDir)) {
     rmSync2(viteCacheDir, { recursive: true });
@@ -1183,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.");
@@ -1212,15 +1266,15 @@ async function previewSite(rootDir, options = {}) {
 import yaml2 from "js-yaml";
 function getVersion() {
   try {
-    let dir = path9.dirname(fileURLToPath3(import.meta.url));
+    let dir = path10.dirname(fileURLToPath3(import.meta.url));
     for (let i = 0;i < 5; i++) {
-      const pkgPath = path9.join(dir, "package.json");
+      const pkgPath = path10.join(dir, "package.json");
       if (existsSync7(pkgPath)) {
         const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
         if (pkg.name === "prev-cli")
           return pkg.version;
       }
-      dir = path9.dirname(dir);
+      dir = path10.dirname(dir);
     }
   } catch {}
   return "unknown";
@@ -1231,13 +1285,14 @@ 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" }
   },
   allowPositionals: true
 });
 var command = positionals[0] || "dev";
-var rootDir = path9.resolve(values.cwd || (command === "config" || command === "create" ? "." : positionals[1]) || ".");
+var rootDir = path10.resolve(values.cwd || (command === "config" || command === "create" ? "." : positionals[1]) || ".");
 function printHelp() {
   console.log(`
 prev - Zero-config documentation site generator
@@ -1260,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
@@ -1345,8 +1401,8 @@ async function clearViteCache(rootDir2) {
       console.log(`  ✓ Removed ${prevCacheDir}`);
     }
   } catch {}
-  const viteCacheDir = path9.join(rootDir2, ".vite");
-  const nodeModulesVite = path9.join(rootDir2, "node_modules", ".vite");
+  const viteCacheDir = path10.join(rootDir2, ".vite");
+  const nodeModulesVite = path10.join(rootDir2, "node_modules", ".vite");
   if (existsSync7(viteCacheDir)) {
     rmSync3(viteCacheDir, { recursive: true });
     cleared++;
@@ -1398,7 +1454,7 @@ function handleConfig(rootDir2, subcommand) {
       break;
     }
     case "init": {
-      const targetPath = path9.join(rootDir2, ".prev.yaml");
+      const targetPath = path10.join(rootDir2, ".prev.yaml");
       if (configPath) {
         console.log(`
   Config already exists: ${configPath}
@@ -1457,7 +1513,7 @@ Available subcommands: show, init, path`);
   }
 }
 function createPreview(rootDir2, name) {
-  const previewDir = path9.join(rootDir2, "previews", name);
+  const previewDir = path10.join(rootDir2, "previews", name);
   if (existsSync7(previewDir)) {
     console.error(`Preview "${name}" already exists at: ${previewDir}`);
     process.exit(1);
@@ -1583,8 +1639,8 @@ export default function App() {
   .dark\\:text-white { color: #fff; }
 }
 `;
-  writeFileSync4(path9.join(previewDir, "App.tsx"), appTsx);
-  writeFileSync4(path9.join(previewDir, "styles.css"), stylesCss);
+  writeFileSync4(path10.join(previewDir, "App.tsx"), appTsx);
+  writeFileSync4(path10.join(previewDir, "styles.css"), stylesCss);
   console.log(`
   ✨ Created preview: previews/${name}/
 
@@ -1619,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.3",
+  "version": "0.23.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

@@ -41,8 +41,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

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

@@ -14,6 +14,7 @@ import {
 } from '@tanstack/react-router'
 import { MDXProvider } from '@mdx-js/react'
 import { pages, sidebar } from 'virtual:prev-pages'
+import { pageModules } from 'virtual:prev-page-modules'
 import { previews } from 'virtual:prev-previews'
 import { Preview } from './Preview'
 import { useDiagrams } from './diagrams'
@@ -64,11 +65,10 @@ function convertToPageTree(items: any[]): PageTree.Root {
   }
 }
 
-// Dynamic imports for MDX pages (include dot directories for --include flag)
-const pageModules = import.meta.glob(['/**/*.{md,mdx}', '/.*/**/*.{md,mdx}'], { eager: true })
-
+// Page modules are dynamically generated by the pages plugin
+// This ensures all MDX files are included regardless of dot-prefixed directories
 function getPageComponent(file: string): React.ComponentType | null {
-  const mod = pageModules[`/${file}`] as { default: React.ComponentType } | undefined
+  const mod = pageModules[`/${file}`]
   return mod?.default || null
 }
 
@@ -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,79 @@
+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>
+  )
+}
 
 export const mdxComponents = {
   Preview,
+  a: MdxLink,
 }

package/src/theme/styles.css

@@ -567,3 +567,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;
+}