@aravindc26/velu 0.12.17 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravindc26/velu",
-  "version": "0.12.17",
+  "version": "0.13.0",
   "description": "A modern documentation site generator powered by Markdown and JSON configuration",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,7 @@
     "dev": "tsx src/cli.ts run"
   },
   "dependencies": {
+    "@fumadocs/mdx-remote": "^1.4.6",
     "@tailwindcss/postcss": "~4.1.18",
     "@types/mdx": "^2.0.13",
     "@types/node": "^22.0.0",

package/src/cli.ts

@@ -571,25 +571,37 @@ async function previewServer(port: number) {
   // Resolve the next binary from the CLI's own node_modules
   const nextBinPath = join(NODE_MODULES_PATH, "next", "dist", "bin", "next");
 
-  const child = spawn(process.execPath, [nextBinPath, "dev", "--port", String(port), "--turbopack"], {
-    cwd: runtimeDir,
-    stdio: ["inherit", "pipe", "inherit"],
-    env: {
-      ...previewServerEnv(),
-      // Align source.config.ts and content-generator on the same content dir
-      PREVIEW_CONTENT_DIR: process.env.PREVIEW_CONTENT_DIR || "./content",
-      WATCHPACK_POLLING: process.env.WATCHPACK_POLLING || "false",
-    },
-  });
+  const previewEnv = {
+    ...previewServerEnv(),
+    // Align source.config.ts and content-generator on the same content dir
+    PREVIEW_CONTENT_DIR: process.env.PREVIEW_CONTENT_DIR || "./content",
+    // Enable preview mode so next.config.mjs produces a server build (not static export)
+    PREVIEW_MODE: "true",
+  };
 
-  // Pipe stdout through while watching for the "Ready" signal to trigger warmup
-  let warmedUp = false;
-  child.stdout?.on("data", (data: Buffer) => {
-    process.stdout.write(data);
-    if (!warmedUp && data.toString().includes("Ready")) {
-      warmedUp = true;
-      warmupRoutes(port);
-    }
+  // Build the app if not already pre-built (Docker pre-builds at image time)
+  const nextOutputDir = join(runtimeDir, ".next");
+  if (!existsSync(nextOutputDir)) {
+    console.log("  Building preview app (first run)...");
+    const buildChild = spawn(process.execPath, [nextBinPath, "build"], {
+      cwd: runtimeDir,
+      stdio: "inherit",
+      env: previewEnv,
+    });
+    await new Promise<void>((res, rej) => {
+      buildChild.on("exit", (code) => {
+        if (code === 0) res();
+        else rej(new Error(`next build exited with code ${code}`));
+      });
+    });
+    console.log("  Build complete.");
+  }
+
+  // Start production server
+  const child = spawn(process.execPath, [nextBinPath, "start", "--port", String(port)], {
+    cwd: runtimeDir,
+    stdio: "inherit",
+    env: previewEnv,
   });
 
   const cleanup = () => child.kill("SIGTERM");
@@ -605,18 +617,6 @@ async function previewServer(port: number) {
   });
 }
 
-/** Pre-warm key routes so Turbopack compiles them before real user requests. */
-function warmupRoutes(port: number) {
-  const routes = [
-    "/api/sessions/_warmup/init",   // compile API route
-    "/_warmup/docs/warmup",         // compile [sessionId]/[...slug] page route
-  ];
-  console.log("  Pre-warming routes...");
-  for (const route of routes) {
-    fetch(`http://localhost:${port}${route}`).catch(() => {});
-  }
-}
-
 // ── run ──────────────────────────────────────────────────────────────────────────
 
 function spawnServer(outDir: string, command: string, port: number, docsDir: string) {

package/src/engine/app/_preview/[sessionId]/[...slug]/layout.tsx

@@ -13,7 +13,7 @@ import {
   getSiteLogoAsset,
 } from '@/lib/velu';
 import { baseOptions } from '@/lib/layout.shared';
-import { getSessionPageTree } from '@/lib/source';
+import { getSessionPageTree } from '@/lib/preview-source';
 import { renderDocsLayout } from '@/lib/docs-layout';
 
 interface LayoutProps {
@@ -74,7 +74,7 @@ export default async function SessionDocsLayout({ children, params }: LayoutProp
   };
 
   const languages = getLanguages(src);
-  const tree = getSessionPageTree(sessionId);
+  const tree = await getSessionPageTree(sessionId);
 
   return renderDocsLayout(
     {

package/src/engine/app/_preview/[sessionId]/[...slug]/page.tsx

@@ -1,4 +1,5 @@
 import { createElement } from 'react';
+import { readFileSync } from 'node:fs';
 import { notFound } from 'next/navigation';
 import { createRelativeLink } from 'fumadocs-ui/mdx';
 import {
@@ -7,14 +8,13 @@ import {
   DocsPage,
   DocsTitle,
 } from 'fumadocs-ui/layouts/notebook/page';
-import { source } from '@/lib/source';
+import { getSessionSource } from '@/lib/preview-source';
 import { getMDXComponents } from '@/mdx-components';
 import { loadSessionConfigSource } from '@/lib/preview-config';
 import {
   getApiConfig,
   getContextualOptions,
   getFooterSocials,
-  getIconLibrary,
 } from '@/lib/velu';
 import { CopyPageButton } from '@/components/copy-page';
 import { VeluImageZoomFallback } from '@/components/image-zoom-fallback';
@@ -138,24 +138,44 @@ function prefixMdxComponentLinks(
 export default async function PreviewPage({ params }: PageProps) {
   const { sessionId, slug } = await params;
 
-  // The full slug for fumadocs lookup includes the session ID prefix
-  const fullSlug = [sessionId, ...slug];
-  const page = source.getPage(fullSlug);
+  const src = await getSessionSource(sessionId);
+  const page = src.getPage(slug);
 
   if (!page) notFound();
 
   const pageDataRecord = page.data as unknown as Record<string, unknown>;
-  const MDX = pageDataRecord.body as any;
+
+  // Dynamic mode: call load() to trigger on-demand MDX compilation
+  const loadFn = pageDataRecord.load as (() => Promise<{ body: any; toc: any }>) | undefined;
+  let MDX: any;
+  let pageToc: any;
+
+  if (typeof loadFn === 'function') {
+    // Dynamic/async entry — compile MDX on demand
+    const loaded = await loadFn();
+    MDX = loaded.body;
+    pageToc = loaded.toc;
+  } else {
+    // Fallback: pre-compiled entry (shouldn't happen in preview mode, but safe)
+    MDX = pageDataRecord.body as any;
+    pageToc = pageDataRecord.toc as any;
+  }
+
   if (typeof MDX !== 'function') notFound();
 
   const configSource = loadSessionConfigSource(sessionId);
-  const iconLibrary = configSource ? getIconLibrary(configSource) : 'fontawesome';
   const footerSocials = configSource ? getFooterSocials(configSource) : [];
   const apiConfig = getApiConfig(configSource ?? undefined);
 
-  const effectiveMarkdown = typeof pageDataRecord.processedMarkdown === 'string'
-    ? String(pageDataRecord.processedMarkdown)
-    : undefined;
+  // Read raw markdown for pattern detection (processedMarkdown not available in dynamic mode)
+  const pageInfo = pageDataRecord.info as { fullPath?: string } | undefined;
+  let effectiveMarkdown: string | undefined;
+  if (pageInfo?.fullPath) {
+    try {
+      effectiveMarkdown = readFileSync(pageInfo.fullPath, 'utf-8');
+    } catch { /* file may not exist */ }
+  }
+
   const hasPanelExamples = typeof effectiveMarkdown === 'string'
     && /<(?:Panel|RequestExample|ResponseExample)(?:\s|>)/.test(effectiveMarkdown);
 
@@ -172,7 +192,6 @@ export default async function PreviewPage({ params }: PageProps) {
   const proxyUrl = apiConfig.playgroundProxyEnabled ? '/api/proxy' : '';
   const isDeprecatedPage = (pageDataRecord.deprecated === true)
     || String((pageDataRecord.status ?? '')).trim().toLowerCase() === 'deprecated';
-  const pageToc = pageDataRecord.toc as any;
   const pageFull = typeof pageDataRecord.full === 'boolean' ? pageDataRecord.full : undefined;
   const hasApiTocRail = shouldShowOpenApi || hasPanelExamples;
   const tableOfContentHeader = hasApiTocRail
@@ -181,10 +200,10 @@ export default async function PreviewPage({ params }: PageProps) {
 
   // Prev/next navigation
   const sessionPrefix = `/${sessionId}`;
-  const allPages = source.getPages();
-  const orderedSessionPages = allPages.filter((p) => p.url.startsWith(`${sessionPrefix}/`));
+  const allPages = src.getPages();
+  const orderedSessionPages = allPages;
   const sourcePageUrl = (page as unknown as { url?: string }).url;
-  const fallbackPath = `/${fullSlug.join('/')}`.replace(/\/{2,}/g, '/');
+  const fallbackPath = `/${slug.join('/')}`.replace(/\/{2,}/g, '/');
   const pageUrl = (typeof sourcePageUrl === 'string' && sourcePageUrl.trim())
     ? sourcePageUrl
     : (fallbackPath === '' ? '/' : fallbackPath);
@@ -232,7 +251,7 @@ export default async function PreviewPage({ params }: PageProps) {
         <MDX
           components={prefixMdxComponentLinks(
             getMDXComponents({
-              a: createRelativeLink(source, page),
+              a: createRelativeLink(src, page),
             }, configSource ?? undefined),
             sessionPrefix,
           )}

package/src/engine/app/_preview/[sessionId]/page.tsx

@@ -1,5 +1,5 @@
 import { redirect } from 'next/navigation';
-import { getSessionPageTree } from '@/lib/source';
+import { getSessionPageTree } from '@/lib/preview-source';
 
 interface PageProps {
   params: Promise<{ sessionId: string }>;
@@ -23,7 +23,7 @@ function findFirstPageUrl(node: any): string | undefined {
 
 export default async function SessionIndexPage({ params }: PageProps) {
   const { sessionId } = await params;
-  const tree = getSessionPageTree(sessionId);
+  const tree = await getSessionPageTree(sessionId);
   const firstUrl = findFirstPageUrl(tree);
 
   if (firstUrl) {

package/src/engine/app/_preview/api/sessions/[sessionId]/init/route.ts

@@ -1,30 +1,8 @@
 import { NextRequest } from 'next/server';
-import { readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
 import { generateSessionContent } from '@/lib/preview-content';
+import { invalidateSessionSource } from '@/lib/preview-source';
 import { verifyApiSecret, unauthorizedResponse } from '@/lib/preview-auth';
 
-/**
- * Toggle a comment in source.config.ts to force fumadocs-mdx to restart
- * and rescan the content directory. Fire-and-forget — don't wait for completion.
- *
- * This is needed because on Cloud Run (gVisor), neither inotify nor chokidar
- * polling reliably detects new files in the content directory.
- */
-function triggerMdxRescan(): void {
-  try {
-    const configPath = resolve(process.cwd(), 'source.config.ts');
-    const marker = '\n// __RELOAD__\n';
-    const content = readFileSync(configPath, 'utf-8');
-    const newContent = content.includes(marker)
-      ? content.replace(marker, '\n')
-      : content + marker;
-    writeFileSync(configPath, newContent, 'utf-8');
-  } catch (e) {
-    console.warn('[PREVIEW] Failed to trigger MDX rescan:', e);
-  }
-}
-
 export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ sessionId: string }> },
@@ -36,9 +14,9 @@ export async function POST(
   try {
     const result = generateSessionContent(sessionId);
 
-    // Fire-and-forget: trigger fumadocs-mdx to discover new content.
-    // The subsequent page request will wait for Turbopack recompilation.
-    triggerMdxRescan();
+    // Invalidate the cached dynamic source so the next page request
+    // re-scans the content directory and picks up the new files.
+    invalidateSessionSource(sessionId);
 
     return Response.json({
       status: 'ready',

package/src/engine/app/_preview/api/sessions/[sessionId]/sync/route.ts

@@ -1,5 +1,6 @@
 import { NextRequest } from 'next/server';
 import { syncSessionFile } from '@/lib/preview-content';
+import { invalidateSessionSource } from '@/lib/preview-source';
 import { verifyApiSecret, unauthorizedResponse } from '@/lib/preview-auth';
 
 export async function POST(
@@ -20,6 +21,10 @@ export async function POST(
 
   try {
     const result = syncSessionFile(sessionId, file);
+
+    // Invalidate cached source so next page request re-scans content
+    invalidateSessionSource(sessionId);
+
     return Response.json({
       status: 'synced',
       file,

package/src/engine/lib/preview-content.ts

@@ -504,6 +504,64 @@ function buildArtifacts(config: VeluConfig, docsDir?: string): BuildArtifacts {
   return { pageMap, metaFiles, firstPage };
 }
 
+// ── Image path rewriting ────────────────────────────────────────────────────
+
+/**
+ * Rewrite image references to use the session assets API.
+ * Handles markdown images, HTML/JSX img tags, and various path formats.
+ * Skips external URLs (http://, https://).
+ */
+function rewriteImagePaths(
+  content: string,
+  sessionId: string,
+  srcFilePath: string,
+): string {
+  const fileDir = dirname(srcFilePath);
+  const workspaceDir = join(WORKSPACE_DIR, sessionId);
+
+  function resolveAssetPath(rawPath: string): string {
+    const trimmed = rawPath.trim();
+    // Skip external URLs
+    if (/^https?:\/\//i.test(trimmed)) return trimmed;
+    // Skip data URIs
+    if (trimmed.startsWith('data:')) return trimmed;
+    // Skip already-rewritten paths
+    if (trimmed.includes(`/api/sessions/${sessionId}/assets/`)) return trimmed;
+
+    let resolved: string;
+    if (trimmed.startsWith('/')) {
+      // Absolute path relative to workspace root
+      resolved = trimmed.replace(/^\/+/, '');
+    } else {
+      // Relative path — resolve relative to source file's directory
+      const abs = resolve(fileDir, trimmed);
+      resolved = relative(workspaceDir, abs).replace(/\\/g, '/');
+    }
+
+    return `/api/sessions/${sessionId}/assets/${resolved}`;
+  }
+
+  // Markdown images: ![alt](path)
+  content = content.replace(
+    /!\[([^\]]*)\]\(([^)]+)\)/g,
+    (match, alt, path) => {
+      const rewritten = resolveAssetPath(path);
+      return `![${alt}](${rewritten})`;
+    },
+  );
+
+  // HTML/JSX img src: <img src="path"> or src={...}
+  content = content.replace(
+    /(<img\b[^>]*?\bsrc\s*=\s*)(["'])([^"']+)\2/gi,
+    (match, prefix, quote, path) => {
+      const rewritten = resolveAssetPath(path);
+      return `${prefix}${quote}${rewritten}${quote}`;
+    },
+  );
+
+  return content;
+}
+
 // ── Page processing ────────────────────────────────────────────────────────
 
 function processPage(
@@ -511,10 +569,16 @@ function processPage(
   destPath: string,
   slug: string,
   variables: Record<string, string>,
+  sessionId?: string,
 ): void {
   let content = readFileSync(srcPath, 'utf-8');
   content = replaceVariablesInString(content, variables);
 
+  // Rewrite image paths to use the assets API
+  if (sessionId) {
+    content = rewriteImagePaths(content, sessionId, srcPath);
+  }
+
   if (!content.startsWith('---')) {
     const titleMatch = content.match(/^#\s+(.+)$/m);
     const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(slug);
@@ -538,6 +602,7 @@ function writeLangContent(
   variables: Record<string, string>,
   isDefault: boolean,
   useLangFolders = false,
+  sessionId?: string,
 ) {
   const storagePrefix = useLangFolders ? langCode : (isDefault ? '' : langCode);
 
@@ -588,7 +653,7 @@ function writeLangContent(
     }
     if (!existsSync(srcPath)) continue;
 
-    processPage(srcPath, destPath, src, variables);
+    processPage(srcPath, destPath, src, variables, sessionId);
   }
 
   const indexPath = storagePrefix
@@ -638,7 +703,7 @@ export function generateSessionContent(sessionId: string): {
         navigation: { ...config.navigation, tabs: langEntry.tabs },
       } as VeluConfig;
       const artifacts = buildArtifacts(langConfig, workspaceDir);
-      writeLangContent(workspaceDir, outputDir, langEntry.language, artifacts, variables, isDefault, true);
+      writeLangContent(workspaceDir, outputDir, langEntry.language, artifacts, variables, isDefault, true, sessionId);
       totalPages += artifacts.pageMap.length;
       if (i === 0) firstPage = artifacts.firstPage;
       rootPages.push(`!${langEntry.language}`);
@@ -658,7 +723,7 @@ export function generateSessionContent(sessionId: string): {
   writeLangContent(
     workspaceDir, outputDir,
     simpleLanguages[0] || 'en', artifacts, variables,
-    true, useLangFolders,
+    true, useLangFolders, sessionId,
   );
 
   let totalPages = artifacts.pageMap.length;
@@ -666,7 +731,7 @@ export function generateSessionContent(sessionId: string): {
   if (simpleLanguages.length > 1) {
     const rootPages = [`!${simpleLanguages[0] || 'en'}`];
     for (const lang of simpleLanguages.slice(1)) {
-      writeLangContent(workspaceDir, outputDir, lang, artifacts, variables, false, true);
+      writeLangContent(workspaceDir, outputDir, lang, artifacts, variables, false, true, sessionId);
       rootPages.push(`!${lang}`);
       totalPages += artifacts.pageMap.length;
     }
@@ -724,7 +789,7 @@ export function syncSessionFile(
 
     if (mapping) {
       const destPath = join(outputDir, `${mapping.dest}.mdx`);
-      processPage(srcPath, destPath, stripped, variables);
+      processPage(srcPath, destPath, stripped, variables, sessionId);
       return { synced: true };
     }
   } catch {
@@ -732,7 +797,7 @@ export function syncSessionFile(
   }
 
   const destPath = join(outputDir, `${stripped}.mdx`);
-  processPage(srcPath, destPath, stripped, variables);
+  processPage(srcPath, destPath, stripped, variables, sessionId);
   return { synced: true };
 }
 

package/src/engine/lib/preview-source.ts

@@ -0,0 +1,217 @@
+/**
+ * Dynamic MDX source for preview mode.
+ *
+ * Instead of relying on fumadocs-mdx's build-time file scanning (which requires
+ * `next dev` + chokidar), this module uses the `dynamic()` runtime API to compile
+ * MDX files on-demand at request time. Content written after `next build` is
+ * discovered by scanning the filesystem directly.
+ *
+ * Used only in preview mode (PREVIEW_MODE=true) — production builds still use
+ * the standard `source.ts` with build-time collections.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { loader } from 'fumadocs-core/source';
+import { dynamic } from 'fumadocs-mdx/runtime/dynamic';
+import type { LazyEntry } from 'fumadocs-mdx/runtime/dynamic';
+import { openApiSidebarMethodBadgePlugin, createStatusBadgesPlugin } from '@core/lib/source-plugins';
+import { getLanguages } from '@/lib/velu';
+import { loadSessionConfigSource } from '@/lib/preview-config';
+
+// Import config exports + core options from source.config.ts so that dynamic()
+// picks up the schema, remark/rehype plugins, etc.
+import * as sourceConfigExports from '../source.config';
+
+const PREVIEW_CONTENT_DIR = process.env.PREVIEW_CONTENT_DIR || './content';
+
+// ── Cache ──────────────────────────────────────────────────────────────────
+
+interface CachedSource {
+  source: ReturnType<typeof loader>;
+  createdAt: number;
+}
+
+const sourceCache = new Map<string, CachedSource>();
+
+// Dynamic instance — singleton, initialized lazily
+let dynamicInstance: Awaited<ReturnType<typeof dynamic>> | null = null;
+let dynamicInitPromise: Promise<Awaited<ReturnType<typeof dynamic>>> | null = null;
+
+async function getDynamic() {
+  if (dynamicInstance) return dynamicInstance;
+  if (dynamicInitPromise) return dynamicInitPromise;
+
+  dynamicInitPromise = dynamic(
+    sourceConfigExports,
+    // CoreOptions — the second argument to dynamic(). Pass empty object to use
+    // defaults from source.config.ts which dynamic() reads via buildConfig().
+    {},
+  ).then((inst) => {
+    dynamicInstance = inst;
+    dynamicInitPromise = null;
+    return inst;
+  });
+
+  return dynamicInitPromise;
+}
+
+// ── File scanning ──────────────────────────────────────────────────────────
+
+function parseFrontmatter(content: string): Record<string, unknown> {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+
+  const output: Record<string, unknown> = {};
+  const lines = match[1].split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const entry = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.+)$/);
+    if (!entry) continue;
+    const key = entry[1];
+    let rawValue = entry[2].trim();
+    // Strip quotes
+    if ((rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+        (rawValue.startsWith("'") && rawValue.endsWith("'"))) {
+      rawValue = rawValue.slice(1, -1);
+    }
+    // Parse booleans
+    if (rawValue === 'true') { output[key] = true; continue; }
+    if (rawValue === 'false') { output[key] = false; continue; }
+    output[key] = rawValue;
+  }
+
+  return output;
+}
+
+function scanContentDir(sessionDir: string): {
+  entries: LazyEntry<Record<string, unknown>>[];
+  metaFiles: Record<string, unknown>;
+} {
+  const entries: LazyEntry<Record<string, unknown>>[] = [];
+  const metaFiles: Record<string, unknown> = {};
+
+  function walk(dir: string) {
+    if (!existsSync(dir)) return;
+    const items = readdirSync(dir, { withFileTypes: true });
+    for (const item of items) {
+      if (item.name.startsWith('.')) continue;
+      const fullPath = join(dir, item.name);
+
+      if (item.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+
+      const relPath = relative(sessionDir, fullPath).replace(/\\/g, '/');
+
+      if (item.name === 'meta.json') {
+        try {
+          const content = readFileSync(fullPath, 'utf-8');
+          metaFiles[relPath] = JSON.parse(content);
+        } catch { /* skip invalid meta */ }
+        continue;
+      }
+
+      if (!item.name.endsWith('.mdx') && !item.name.endsWith('.md')) continue;
+
+      try {
+        const content = readFileSync(fullPath, 'utf-8');
+        const frontmatter = parseFrontmatter(content);
+
+        // Ensure title exists
+        if (!frontmatter.title) {
+          const titleMatch = content.match(/^#\s+(.+)$/m);
+          frontmatter.title = titleMatch ? titleMatch[1] : item.name.replace(/\.mdx?$/, '');
+        }
+
+        entries.push({
+          info: {
+            path: relPath,
+            fullPath,
+          },
+          data: frontmatter,
+        });
+      } catch { /* skip unreadable files */ }
+    }
+  }
+
+  walk(sessionDir);
+  return { entries, metaFiles };
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Get a fumadocs source loader for a specific session's content.
+ * Scans the content directory at call time and compiles MDX on-demand.
+ */
+export async function getSessionSource(sessionId: string) {
+  const cached = sourceCache.get(sessionId);
+  if (cached) return cached.source;
+
+  const sessionDir = join(PREVIEW_CONTENT_DIR, sessionId);
+  if (!existsSync(sessionDir)) {
+    // Return an empty source if no content yet
+    const emptySource = loader({
+      baseUrl: '/',
+      source: { files: [] },
+    });
+    return emptySource;
+  }
+
+  const dyn = await getDynamic();
+  const { entries, metaFiles } = scanContentDir(sessionDir);
+
+  const collection = await dyn.docs('docs', sessionDir, metaFiles, entries);
+  const fumadocsSource = collection.toFumadocsSource();
+
+  const configSource = loadSessionConfigSource(sessionId);
+  const languages = configSource ? getLanguages(configSource) : [];
+  const defaultLanguage = languages[0] ?? 'en';
+
+  const src = loader({
+    baseUrl: '/',
+    source: fumadocsSource as any,
+    plugins: [
+      openApiSidebarMethodBadgePlugin() as any,
+      createStatusBadgesPlugin(),
+    ],
+    i18n:
+      languages.length > 1
+        ? {
+            languages,
+            defaultLanguage,
+            hideLocale: 'default-locale',
+            parser: 'dir',
+            fallbackLanguage: defaultLanguage,
+          }
+        : undefined,
+  });
+
+  sourceCache.set(sessionId, { source: src, createdAt: Date.now() });
+  return src;
+}
+
+/**
+ * Invalidate the cached source for a session.
+ * Call after content generation or sync so the next request re-scans.
+ */
+export function invalidateSessionSource(sessionId: string): void {
+  sourceCache.delete(sessionId);
+}
+
+/**
+ * Get the page tree filtered to a specific session's content.
+ * Unlike source.ts's synchronous version, this is async because
+ * it may need to initialize the dynamic MDX compiler.
+ */
+export async function getSessionPageTree(sessionId: string) {
+  const src = await getSessionSource(sessionId);
+  const fullTree = src.getPageTree();
+
+  // In preview-source, content is loaded directly from the session dir,
+  // so the page tree is already scoped to that session's content.
+  // No need to filter by session prefix — URLs are relative to the session.
+  return fullTree;
+}

package/src/engine/next.config.mjs

@@ -8,13 +8,13 @@ const withMDX = createMDX({
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: false,
-  output: process.env.NODE_ENV === 'production' ? 'export' : undefined,
+  output: process.env.PREVIEW_MODE ? undefined : (process.env.NODE_ENV === 'production' ? 'export' : undefined),
   basePath: process.env.VELU_BASE_PATH || '',
   // For static hosts without rewrite rules, emit directory routes
   // (e.g. /docs/page/index.html) so extensionless URLs resolve.
   trailingSlash: true,
   skipTrailingSlashRedirect: true,
-  distDir: 'dist',
+  distDir: process.env.PREVIEW_MODE ? '.next' : 'dist',
   devIndicators: false,
   turbopack: {
     root: resolve('..'),