@aravindc26/velu 0.11.22 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravindc26/velu",
-  "version": "0.11.22",
+  "version": "0.12.1",
   "description": "A modern documentation site generator powered by Markdown and JSON configuration",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -35,18 +35,22 @@ function printHelp() {
   velu — documentation site generator
 
   Usage:
-    velu version           Print Velu CLI version
-    velu init              Scaffold a new docs project with example files
-    velu lint              Validate docs.json (or velu.json) and check referenced pages
-    velu run [--port N]    Build site and start dev server (default: 4321)
-    velu build             Build a deployable static site (SSG)
-    velu paths             Output navigation paths and source files as JSON (grouped by language)
+    velu version                Print Velu CLI version
+    velu init                   Scaffold a new docs project with example files
+    velu lint                   Validate docs.json (or velu.json) and check referenced pages
+    velu run [--port N]         Build site and start dev server (default: 4321)
+    velu build                  Build a deployable static site (SSG)
+    velu paths                  Output navigation paths and source files as JSON (grouped by language)
+    velu preview-server [opts]  Start multi-tenant preview server (no docs.json needed)
 
   Options:
     --version         Show Velu CLI version
     --port <number>   Port for the dev server (default: 4321)
     --help            Show this help message
 
+  Preview server options:
+    --port <number>   Port for the preview server (default: 8080)
+
   Run lint/run/build/paths from a directory containing docs.json (or velu.json).
 `);
 }
@@ -483,6 +487,52 @@ async function buildSite(docsDir: string) {
   console.log(`\n📁 Static site output: ${staticOutDir}`);
 }
 
+// ── preview-server ───────────────────────────────────────────────────────────────
+
+const PREVIEW_ENGINE_DIR = (() => {
+  const dev = join(PACKAGE_ROOT, "src", "preview-engine");
+  const packaged = join(dirname(__filename), "preview-engine");
+  return existsSync(dev) ? dev : packaged;
+})();
+
+function previewServerEnv(): NodeJS.ProcessEnv {
+  const existing = process.env.NODE_PATH || "";
+  return {
+    ...process.env,
+    NODE_PATH: existing ? `${NODE_MODULES_PATH}${delimiter}${existing}` : NODE_MODULES_PATH,
+  };
+}
+
+async function previewServer(port: number) {
+  const runtimeDir = join(PACKAGE_ROOT, ".velu-preview-out");
+
+  // Clean and copy preview engine to runtime dir
+  try { rmSync(runtimeDir, { recursive: true, force: true }); } catch {}
+  copyDirMerge(PREVIEW_ENGINE_DIR, runtimeDir);
+
+  console.log(`  Starting preview server on port ${port}...`);
+  console.log(`  Preview content dir: ${process.env.PREVIEW_CONTENT_DIR || "(default)"}`);
+  console.log(`  Workspace dir: ${process.env.WORKSPACE_DIR || "(default)"}`);
+
+  // Resolve the next binary from the CLI's own node_modules
+  const nextBinPath = join(NODE_MODULES_PATH, "next", "dist", "bin", "next");
+
+  const child = spawn("node", [nextBinPath, "dev", "--port", String(port), "--turbopack"], {
+    cwd: runtimeDir,
+    stdio: "inherit",
+    env: {
+      ...previewServerEnv(),
+      WATCHPACK_POLLING: process.env.WATCHPACK_POLLING || "true",
+    },
+  });
+
+  child.on("exit", (code) => process.exit(code ?? 0));
+
+  const cleanup = () => child.kill("SIGTERM");
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+
 // ── run ──────────────────────────────────────────────────────────────────────────
 
 function spawnServer(outDir: string, command: string, port: number, docsDir: string) {
@@ -528,6 +578,19 @@ if (command === "init") {
   process.exit(0);
 }
 
+// preview-server doesn't require docs.json
+if (command === "preview-server") {
+  const portIdx = args.indexOf("--port");
+  const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : 8080;
+  if (isNaN(port)) {
+    console.error("❌ Invalid port number.");
+    process.exit(1);
+  }
+  await previewServer(port);
+  // previewServer keeps running (child process), so we never reach here
+  process.exit(0);
+}
+
 if (!resolveConfigPath(docsDir)) {
   console.error("❌ No docs.json or velu.json found in the current directory.");
   console.error("   Run `velu init` to scaffold a new project, or run from a directory containing docs.json.");

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

@@ -0,0 +1,41 @@
+import { notFound } from 'next/navigation';
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from 'fumadocs-ui/layouts/notebook/page';
+import { source } from '@/lib/source';
+
+interface PageProps {
+  params: Promise<{ sessionId: string; slug: string[] }>;
+}
+
+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);
+
+  if (!page) notFound();
+
+  const pageDataRecord = page.data as unknown as Record<string, unknown>;
+  const MDX = pageDataRecord.body as any;
+  if (typeof MDX !== 'function') notFound();
+
+  return (
+    <DocsPage
+      toc={pageDataRecord.toc as any}
+      footer={{ enabled: false }}
+    >
+      <DocsTitle>{page.data.title}</DocsTitle>
+      {page.data.description ? (
+        <DocsDescription>{page.data.description}</DocsDescription>
+      ) : null}
+      <DocsBody>
+        <MDX />
+      </DocsBody>
+    </DocsPage>
+  );
+}

package/src/preview-engine/app/[sessionId]/layout.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
+import { getSessionPageTree } from '@/lib/source';
+
+interface LayoutProps {
+  children: ReactNode;
+  params: Promise<{ sessionId: string }>;
+}
+
+export default async function SessionLayout({ children, params }: LayoutProps) {
+  const { sessionId } = await params;
+  const tree = getSessionPageTree(sessionId);
+
+  return (
+    <DocsLayout
+      tree={tree}
+      sidebar={{ collapsible: true }}
+      themeSwitch={{ enabled: false }}
+    >
+      {children}
+    </DocsLayout>
+  );
+}

package/src/preview-engine/app/[sessionId]/page.tsx

@@ -0,0 +1,35 @@
+import { redirect } from 'next/navigation';
+import { source, getSessionPageTree } from '@/lib/source';
+
+interface PageProps {
+  params: Promise<{ sessionId: string }>;
+}
+
+function findFirstPageUrl(node: any): string | undefined {
+  if (!node || typeof node !== 'object') return undefined;
+  if (node.type === 'page' && !node.external && typeof node.url === 'string') {
+    return node.url;
+  }
+  if (node.type === 'folder' && typeof node.index?.url === 'string') {
+    return node.index.url;
+  }
+  const children = Array.isArray(node.children) ? node.children : [];
+  for (const child of children) {
+    const url = findFirstPageUrl(child);
+    if (url) return url;
+  }
+  return undefined;
+}
+
+export default async function SessionIndexPage({ params }: PageProps) {
+  const { sessionId } = await params;
+  const tree = getSessionPageTree(sessionId);
+  const firstUrl = findFirstPageUrl(tree);
+
+  if (firstUrl) {
+    redirect(firstUrl.endsWith('/') ? firstUrl : `${firstUrl}/`);
+  }
+
+  // Fallback: redirect to session root
+  redirect(`/${sessionId}/`);
+}

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

@@ -0,0 +1,29 @@
+import { NextRequest } from 'next/server';
+import { generateSessionContent } from '@/lib/content-generator';
+import { verifyApiSecret, unauthorizedResponse } from '@/lib/auth';
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ sessionId: string }> },
+) {
+  if (!verifyApiSecret(request)) return unauthorizedResponse();
+
+  const { sessionId } = await params;
+
+  try {
+    const result = generateSessionContent(sessionId);
+    return Response.json({
+      status: 'ready',
+      url: `/${sessionId}/`,
+      firstPage: result.firstPage,
+      pageCount: result.pageCount,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    console.error(`[PREVIEW] Init failed for session ${sessionId}:`, message);
+    return Response.json(
+      { status: 'error', error: message },
+      { status: 500 },
+    );
+  }
+}

package/src/preview-engine/app/api/sessions/[sessionId]/route.ts

@@ -0,0 +1,26 @@
+import { NextRequest } from 'next/server';
+import { removeSessionContent } from '@/lib/content-generator';
+import { clearSessionCache } from '@/lib/session-config';
+import { verifyApiSecret, unauthorizedResponse } from '@/lib/auth';
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ sessionId: string }> },
+) {
+  if (!verifyApiSecret(request)) return unauthorizedResponse();
+
+  const { sessionId } = await params;
+
+  try {
+    removeSessionContent(sessionId);
+    clearSessionCache(sessionId);
+    return Response.json({ status: 'removed', sessionId });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    console.error(`[PREVIEW] Cleanup failed for session ${sessionId}:`, message);
+    return Response.json(
+      { status: 'error', error: message },
+      { status: 500 },
+    );
+  }
+}

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

@@ -0,0 +1,36 @@
+import { NextRequest } from 'next/server';
+import { syncSessionFile } from '@/lib/content-generator';
+import { verifyApiSecret, unauthorizedResponse } from '@/lib/auth';
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ sessionId: string }> },
+) {
+  if (!verifyApiSecret(request)) return unauthorizedResponse();
+
+  const { sessionId } = await params;
+  const file = request.nextUrl.searchParams.get('file');
+
+  if (!file) {
+    return Response.json(
+      { error: 'Missing "file" query parameter' },
+      { status: 400 },
+    );
+  }
+
+  try {
+    const result = syncSessionFile(sessionId, file);
+    return Response.json({
+      status: 'synced',
+      file,
+      ...result,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    console.error(`[PREVIEW] Sync failed for session ${sessionId}, file ${file}:`, message);
+    return Response.json(
+      { status: 'error', error: message },
+      { status: 500 },
+    );
+  }
+}

package/src/preview-engine/app/global.css

@@ -0,0 +1,3 @@
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/neutral.css';
+@import 'fumadocs-ui/css/preset.css';

package/src/preview-engine/app/layout.tsx

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+import './global.css';
+
+export const metadata = {
+  title: 'Preview',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="min-h-screen" suppressHydrationWarning>
+        {children}
+      </body>
+    </html>
+  );
+}

package/src/preview-engine/app/page.tsx

@@ -0,0 +1,12 @@
+export default function Home() {
+  return (
+    <div style={{ padding: '2rem', fontFamily: 'system-ui' }}>
+      <h1>Velu Preview Service</h1>
+      <p>Multi-tenant documentation preview server.</p>
+      <p>
+        Access a session&apos;s preview at{' '}
+        <code>/{'{sessionId}'}/docs/...</code>
+      </p>
+    </div>
+  );
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Shared API authentication via PREVIEW_API_SECRET.
+ */
+import { NextRequest } from 'next/server';
+
+const PREVIEW_API_SECRET = process.env.PREVIEW_API_SECRET || '';
+
+export function verifyApiSecret(request: NextRequest): boolean {
+  if (!PREVIEW_API_SECRET) return true; // No secret configured — allow all
+  const header = request.headers.get('x-preview-secret') || '';
+  return header === PREVIEW_API_SECRET;
+}
+
+export function unauthorizedResponse() {
+  return Response.json({ error: 'Unauthorized' }, { status: 401 });
+}

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

@@ -0,0 +1,551 @@
+/**
+ * Content generator for preview sessions.
+ *
+ * Reads a workspace directory (docs.json + MDX source files) and writes
+ * processed content to an output directory that fumadocs-mdx scans.
+ *
+ * This is a simplified version of the build pipeline in build.ts/_server.mjs,
+ * focused only on content generation (no engine scaffolding, theme CSS, etc.).
+ */
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, extname, join, relative } from 'node:path';
+
+const PREVIEW_CONTENT_DIR = process.env.PREVIEW_CONTENT_DIR || './content';
+const WORKSPACE_DIR = process.env.WORKSPACE_DIR || '/mnt/nfs_share/editor_sessions';
+
+const PRIMARY_CONFIG_NAME = 'docs.json';
+const LEGACY_CONFIG_NAME = 'velu.json';
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface VeluConfig {
+  navigation: {
+    tabs?: VeluTab[];
+    languages?: Array<{ language: string; tabs: VeluTab[] }>;
+    anchors?: any[];
+    [key: string]: unknown;
+  };
+  languages?: string[];
+  openapi?: unknown;
+  variables?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+interface VeluTab {
+  tab: string;
+  slug?: string;
+  href?: string;
+  pages?: Array<string | VeluSeparator | VeluLink>;
+  groups?: VeluGroup[];
+  openapi?: unknown;
+  [key: string]: unknown;
+}
+
+interface VeluGroup {
+  group: string;
+  slug?: string;
+  pages: Array<string | VeluGroup | VeluSeparator | VeluLink>;
+  description?: string;
+  openapi?: unknown;
+  [key: string]: unknown;
+}
+
+interface VeluSeparator { separator: string }
+interface VeluLink { href: string; label: string; icon?: string }
+
+interface PageMapping {
+  src: string;
+  dest: string;
+  kind: 'file' | 'openapi-operation';
+  title?: string;
+  description?: string;
+  openapiSpec?: string;
+  openapiMethod?: string;
+  openapiEndpoint?: string;
+  deprecated?: boolean;
+  version?: string;
+  content?: string;
+}
+
+interface MetaFile {
+  dir: string;
+  data: { pages: string[]; title?: string; description?: string };
+}
+
+interface BuildArtifacts {
+  pageMap: PageMapping[];
+  metaFiles: MetaFile[];
+  firstPage: string;
+}
+
+// ── Config loading ─────────────────────────────────────────────────────────
+
+function resolveConfigPath(docsDir: string): string | null {
+  const primary = join(docsDir, PRIMARY_CONFIG_NAME);
+  if (existsSync(primary)) return primary;
+  const legacy = join(docsDir, LEGACY_CONFIG_NAME);
+  if (existsSync(legacy)) return legacy;
+  return null;
+}
+
+function resolveVariables(
+  variables: Record<string, string> | undefined,
+): Record<string, string> {
+  if (!variables) return {};
+  const resolved: Record<string, string> = {};
+  const MAX_DEPTH = 10;
+
+  for (const [key, rawValue] of Object.entries(variables)) {
+    let value = rawValue;
+    for (let depth = 0; depth < MAX_DEPTH; depth++) {
+      const replaced = value.replace(
+        /\{\{(\w+)\}\}/g,
+        (_, name) => variables[name] ?? `{{${name}}}`,
+      );
+      if (replaced === value) break;
+      value = replaced;
+    }
+    resolved[key] = value;
+  }
+  return resolved;
+}
+
+function replaceVariablesInString(
+  content: string,
+  variables: Record<string, string>,
+): string {
+  if (!content || Object.keys(variables).length === 0) return content;
+  return content.replace(
+    /\{\{(\w+)\}\}/g,
+    (match, name) => variables[name] ?? match,
+  );
+}
+
+function loadConfig(docsDir: string): {
+  config: VeluConfig;
+  variables: Record<string, string>;
+} {
+  const configPath = resolveConfigPath(docsDir);
+  if (!configPath) {
+    throw new Error(`No docs.json or velu.json found in ${docsDir}`);
+  }
+  const raw = JSON.parse(readFileSync(configPath, 'utf-8')) as VeluConfig;
+  const variables = resolveVariables(raw.variables);
+  return { config: raw, variables };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function isSeparator(item: unknown): item is VeluSeparator {
+  return typeof item === 'object' && item !== null && 'separator' in item;
+}
+
+function isLink(item: unknown): item is VeluLink {
+  return typeof item === 'object' && item !== null && 'href' in item && 'label' in item;
+}
+
+function isGroup(item: unknown): item is VeluGroup {
+  return typeof item === 'object' && item !== null && 'group' in item;
+}
+
+function pageBasename(page: string): string {
+  const parts = page.split('/').filter(Boolean);
+  return parts[parts.length - 1] ?? page;
+}
+
+function pageLabelFromSlug(slug: string): string {
+  const base = pageBasename(slug);
+  return base
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function sanitizeFrontmatterValue(value: string): string {
+  return value.replace(/\r?\n+/g, ' ').replace(/"/g, '\\"').trim();
+}
+
+// ── Build artifacts ────────────────────────────────────────────────────────
+
+function buildArtifacts(config: VeluConfig): BuildArtifacts {
+  const pageMap: PageMapping[] = [];
+  const metaFiles: MetaFile[] = [];
+  const rootTabs = (config.navigation.tabs || []).filter((tab) => !tab.href);
+  const rootPages = rootTabs.map((tab) => tab.slug);
+  let firstPage = 'quickstart';
+  let hasFirstPage = false;
+  const usedDestinations = new Set<string>();
+
+  function trackFirstPage(dest: string) {
+    if (!hasFirstPage) {
+      firstPage = dest;
+      hasFirstPage = true;
+    }
+  }
+
+  function metaEntry(item: string | VeluSeparator | VeluLink): string {
+    if (typeof item === 'string') return item;
+    if (isSeparator(item)) return `---${item.separator}---`;
+    if (isLink(item)) {
+      return item.icon
+        ? `[${item.icon}][${item.label}](${item.href})`
+        : `[${item.label}](${item.href})`;
+    }
+    return String(item);
+  }
+
+  function uniqueDestination(dest: string): string {
+    if (!usedDestinations.has(dest)) {
+      usedDestinations.add(dest);
+      return dest;
+    }
+    let count = 2;
+    while (usedDestinations.has(`${dest}-${count}`)) count += 1;
+    const candidate = `${dest}-${count}`;
+    usedDestinations.add(candidate);
+    return candidate;
+  }
+
+  function processGroup(
+    group: VeluGroup,
+    parentDir: string,
+    inheritedSpec?: string,
+  ) {
+    const groupSlug = group.slug || pageBasename(group.group).toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    const groupDir = `${parentDir}/${groupSlug}`;
+    const groupMetaPages: string[] = [];
+    const groupSpec = typeof group.openapi === 'string' ? group.openapi : inheritedSpec;
+
+    for (const item of group.pages) {
+      if (typeof item === 'string') {
+        const dest = uniqueDestination(`${groupDir}/${pageBasename(item)}`);
+        pageMap.push({ src: item, dest, kind: 'file' });
+        groupMetaPages.push(pageBasename(item));
+        trackFirstPage(dest);
+      } else if (isGroup(item)) {
+        const nestedSlug = item.slug || pageBasename(item.group).toLowerCase().replace(/[^a-z0-9]+/g, '-');
+        groupMetaPages.push(nestedSlug);
+        processGroup(item, groupDir, groupSpec);
+      } else if (isSeparator(item) || isLink(item)) {
+        groupMetaPages.push(metaEntry(item));
+      }
+    }
+
+    metaFiles.push({
+      dir: groupDir,
+      data: {
+        title: group.group,
+        ...(group.description ? { description: group.description } : {}),
+        pages: groupMetaPages,
+      },
+    });
+  }
+
+  function processTab(tab: VeluTab) {
+    const tabSlug = tab.slug || tab.tab.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    const tabDir = tabSlug;
+    const tabMetaPages: string[] = [];
+    const tabSpec = typeof tab.openapi === 'string' ? tab.openapi : undefined;
+
+    // Process top-level pages in this tab
+    if (tab.pages) {
+      for (const item of tab.pages) {
+        if (typeof item === 'string') {
+          const dest = uniqueDestination(`${tabDir}/${pageBasename(item)}`);
+          pageMap.push({ src: item, dest, kind: 'file' });
+          tabMetaPages.push(pageBasename(item));
+          trackFirstPage(dest);
+        } else if (isSeparator(item) || isLink(item)) {
+          tabMetaPages.push(metaEntry(item));
+        }
+      }
+    }
+
+    // Process groups
+    if (tab.groups) {
+      for (const group of tab.groups) {
+        const groupSlug = group.slug || pageBasename(group.group).toLowerCase().replace(/[^a-z0-9]+/g, '-');
+        tabMetaPages.push(groupSlug);
+        processGroup(group, tabDir, tabSpec);
+      }
+    }
+
+    metaFiles.push({
+      dir: tabDir,
+      data: { title: tab.tab, pages: tabMetaPages },
+    });
+  }
+
+  // Process all tabs
+  for (const tab of rootTabs) {
+    processTab(tab);
+  }
+
+  // Root meta.json lists the tab slugs
+  metaFiles.push({
+    dir: '',
+    data: { pages: rootPages.filter((p): p is string => typeof p === 'string') },
+  });
+
+  return { pageMap, metaFiles, firstPage };
+}
+
+// ── Page processing ────────────────────────────────────────────────────────
+
+function processPage(
+  srcPath: string,
+  destPath: string,
+  slug: string,
+  variables: Record<string, string>,
+): void {
+  let content = readFileSync(srcPath, 'utf-8');
+  content = replaceVariablesInString(content, variables);
+
+  if (!content.startsWith('---')) {
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(slug);
+    if (titleMatch) {
+      content = content.replace(/^#\s+.+$/m, '').trimStart();
+    }
+    content = `---\ntitle: "${sanitizeFrontmatterValue(title)}"\n---\n\n${content}`;
+  }
+
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, content, 'utf-8');
+}
+
+// ── Content writing ────────────────────────────────────────────────────────
+
+function writeLangContent(
+  docsDir: string,
+  contentDir: string,
+  langCode: string,
+  artifacts: BuildArtifacts,
+  variables: Record<string, string>,
+  isDefault: boolean,
+  useLangFolders = false,
+) {
+  const storagePrefix = useLangFolders ? langCode : (isDefault ? '' : langCode);
+
+  // Write meta files
+  const metas = storagePrefix
+    ? artifacts.metaFiles.map((m) => ({
+        dir: m.dir ? `${storagePrefix}/${m.dir}` : storagePrefix,
+        data: { ...m.data },
+      }))
+    : artifacts.metaFiles;
+
+  for (const meta of metas) {
+    const metaPath = join(contentDir, meta.dir, 'meta.json');
+    mkdirSync(dirname(metaPath), { recursive: true });
+    writeFileSync(metaPath, JSON.stringify(meta.data, null, 2) + '\n', 'utf-8');
+  }
+
+  // Copy and process pages
+  for (const mapping of artifacts.pageMap) {
+    const destPath = join(
+      contentDir,
+      storagePrefix ? `${storagePrefix}/${mapping.dest}.mdx` : `${mapping.dest}.mdx`,
+    );
+
+    if (mapping.kind === 'openapi-operation') {
+      mkdirSync(dirname(destPath), { recursive: true });
+      const operationLabel = `${mapping.openapiMethod ?? 'GET'} ${mapping.openapiEndpoint ?? '/'}`;
+      const title = sanitizeFrontmatterValue(mapping.title ?? operationLabel);
+      const openapi = operationLabel.replace(/"/g, '\\"');
+      const descriptionLine = mapping.description
+        ? `\ndescription: "${sanitizeFrontmatterValue(mapping.description)}"`
+        : '';
+      writeFileSync(
+        destPath,
+        `---\ntitle: "${title}"${descriptionLine}\nopenapi: "${openapi}"\n---\n`,
+        'utf-8',
+      );
+      continue;
+    }
+
+    const src = mapping.src;
+    let srcPath = join(docsDir, `${src}.mdx`);
+    if (!existsSync(srcPath)) {
+      srcPath = join(docsDir, `${src}.md`);
+    }
+    if (!existsSync(srcPath)) continue;
+
+    processPage(srcPath, destPath, src, variables);
+  }
+
+  // Index page redirect
+  const urlPrefix = isDefault ? '' : langCode;
+  const href = urlPrefix
+    ? `/${urlPrefix}/${artifacts.firstPage}/`
+    : `/${artifacts.firstPage}/`;
+  const indexPath = storagePrefix
+    ? join(contentDir, storagePrefix, 'index.mdx')
+    : join(contentDir, 'index.mdx');
+  writeFileSync(
+    indexPath,
+    `---\ntitle: "Overview"\n---\n\nWelcome to the documentation.\n`,
+    'utf-8',
+  );
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate all content for a session from its workspace.
+ * Reads from workspaceDir (docs.json + MDX sources) and writes
+ * processed content to outputDir.
+ */
+export function generateSessionContent(sessionId: string): {
+  firstPage: string;
+  pageCount: number;
+} {
+  const workspaceDir = join(WORKSPACE_DIR, sessionId);
+  const outputDir = join(PREVIEW_CONTENT_DIR, sessionId);
+
+  // Clean previous content
+  if (existsSync(outputDir)) {
+    rmSync(outputDir, { recursive: true, force: true });
+  }
+  mkdirSync(outputDir, { recursive: true });
+
+  const { config, variables } = loadConfig(workspaceDir);
+  const navLanguages = config.navigation.languages;
+  const simpleLanguages = config.languages || [];
+
+  if (navLanguages && navLanguages.length > 0) {
+    // Per-language navigation
+    const rootPages: string[] = [];
+    let totalPages = 0;
+    let firstPage = 'quickstart';
+
+    for (let i = 0; i < navLanguages.length; i++) {
+      const langEntry = navLanguages[i];
+      const isDefault = i === 0;
+      const langConfig = {
+        ...config,
+        navigation: { ...config.navigation, tabs: langEntry.tabs },
+      } as VeluConfig;
+      const artifacts = buildArtifacts(langConfig);
+      writeLangContent(workspaceDir, outputDir, langEntry.language, artifacts, variables, isDefault, true);
+      totalPages += artifacts.pageMap.length;
+      if (i === 0) firstPage = artifacts.firstPage;
+      rootPages.push(`!${langEntry.language}`);
+    }
+
+    writeFileSync(
+      join(outputDir, 'meta.json'),
+      JSON.stringify({ pages: rootPages }, null, 2) + '\n',
+      'utf-8',
+    );
+
+    return { firstPage, pageCount: totalPages };
+  }
+
+  // Simple (single-lang or same-nav multi-lang)
+  const artifacts = buildArtifacts(config);
+  const useLangFolders = simpleLanguages.length > 1;
+  writeLangContent(
+    workspaceDir, outputDir,
+    simpleLanguages[0] || 'en', artifacts, variables,
+    true, useLangFolders,
+  );
+
+  let totalPages = artifacts.pageMap.length;
+
+  if (simpleLanguages.length > 1) {
+    const rootPages = [`!${simpleLanguages[0] || 'en'}`];
+    for (const lang of simpleLanguages.slice(1)) {
+      writeLangContent(workspaceDir, outputDir, lang, artifacts, variables, false, true);
+      rootPages.push(`!${lang}`);
+      totalPages += artifacts.pageMap.length;
+    }
+    writeFileSync(
+      join(outputDir, 'meta.json'),
+      JSON.stringify({ pages: rootPages }, null, 2) + '\n',
+      'utf-8',
+    );
+  }
+
+  return { firstPage: artifacts.firstPage, pageCount: totalPages };
+}
+
+/**
+ * Sync a single file after an edit in the workspace.
+ * Re-reads the file from the workspace and writes the processed
+ * version to the preview content directory.
+ */
+export function syncSessionFile(
+  sessionId: string,
+  filePath: string,
+): { synced: boolean } {
+  const workspaceDir = join(WORKSPACE_DIR, sessionId);
+  const outputDir = join(PREVIEW_CONTENT_DIR, sessionId);
+
+  // If this is a config file change, do a full regeneration
+  if (filePath === PRIMARY_CONFIG_NAME || filePath === LEGACY_CONFIG_NAME) {
+    generateSessionContent(sessionId);
+    return { synced: true };
+  }
+
+  // Load config for variable substitution
+  let variables: Record<string, string> = {};
+  try {
+    const result = loadConfig(workspaceDir);
+    variables = result.variables;
+  } catch {
+    // Config might not exist yet
+  }
+
+  // Find the source file
+  const stripped = filePath.replace(/\.(mdx?|md)$/, '');
+  let srcPath = join(workspaceDir, filePath);
+  if (!existsSync(srcPath)) {
+    srcPath = join(workspaceDir, `${stripped}.mdx`);
+  }
+  if (!existsSync(srcPath)) {
+    srcPath = join(workspaceDir, `${stripped}.md`);
+  }
+  if (!existsSync(srcPath)) {
+    return { synced: false };
+  }
+
+  // We need to figure out where this file maps in the output.
+  // Rebuild from config to get the page map, then find the mapping for this file.
+  try {
+    const { config } = loadConfig(workspaceDir);
+    const artifacts = buildArtifacts(config);
+    const mapping = artifacts.pageMap.find((m) => {
+      return m.src === stripped || m.src === filePath;
+    });
+
+    if (mapping) {
+      const destPath = join(outputDir, `${mapping.dest}.mdx`);
+      processPage(srcPath, destPath, stripped, variables);
+      return { synced: true };
+    }
+  } catch {
+    // Fall through to direct copy
+  }
+
+  // Fallback: try to process the file directly
+  const destPath = join(outputDir, `${stripped}.mdx`);
+  processPage(srcPath, destPath, stripped, variables);
+  return { synced: true };
+}
+
+/**
+ * Remove all preview content for a session.
+ */
+export function removeSessionContent(sessionId: string): void {
+  const outputDir = join(PREVIEW_CONTENT_DIR, sessionId);
+  if (existsSync(outputDir)) {
+    rmSync(outputDir, { recursive: true, force: true });
+  }
+}

package/src/preview-engine/lib/session-config.ts

@@ -0,0 +1,86 @@
+/**
+ * Per-session configuration cache.
+ * Reads docs.json from workspace directories and caches the parsed config.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const WORKSPACE_DIR = process.env.WORKSPACE_DIR || '/mnt/nfs_share/editor_sessions';
+const PRIMARY_CONFIG_NAME = 'docs.json';
+const LEGACY_CONFIG_NAME = 'velu.json';
+
+interface SessionConfig {
+  name?: string;
+  description?: string;
+  title?: string;
+  theme?: string;
+  colors?: { primary?: string; light?: string; dark?: string };
+  navigation: {
+    tabs?: any[];
+    languages?: any[];
+    anchors?: any[];
+    [key: string]: unknown;
+  };
+  languages?: string[];
+  openapi?: unknown;
+  [key: string]: unknown;
+}
+
+interface CachedSession {
+  config: SessionConfig;
+  rawConfig: Record<string, unknown>;
+  loadedAt: number;
+}
+
+const sessionCache = new Map<string, CachedSession>();
+const CACHE_TTL_MS = 60_000; // 1 minute
+
+function resolveWorkspaceConfigPath(sessionId: string): string | null {
+  const wsDir = join(WORKSPACE_DIR, sessionId);
+  const primary = join(wsDir, PRIMARY_CONFIG_NAME);
+  if (existsSync(primary)) return primary;
+  const legacy = join(wsDir, LEGACY_CONFIG_NAME);
+  if (existsSync(legacy)) return legacy;
+  return null;
+}
+
+export function getSessionConfig(sessionId: string): SessionConfig | null {
+  const cached = sessionCache.get(sessionId);
+  if (cached && Date.now() - cached.loadedAt < CACHE_TTL_MS) {
+    return cached.config;
+  }
+
+  const configPath = resolveWorkspaceConfigPath(sessionId);
+  if (!configPath) return null;
+
+  try {
+    const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    const config = raw as SessionConfig;
+    sessionCache.set(sessionId, {
+      config,
+      rawConfig: raw,
+      loadedAt: Date.now(),
+    });
+    return config;
+  } catch {
+    return null;
+  }
+}
+
+export function getSessionRawConfig(sessionId: string): Record<string, unknown> | null {
+  getSessionConfig(sessionId); // ensure loaded
+  return sessionCache.get(sessionId)?.rawConfig ?? null;
+}
+
+export function clearSessionCache(sessionId: string): void {
+  sessionCache.delete(sessionId);
+}
+
+export function getWorkspaceDir(sessionId: string): string {
+  return join(WORKSPACE_DIR, sessionId);
+}
+
+export function getSiteName(sessionId: string): string {
+  const config = getSessionConfig(sessionId);
+  return config?.name || config?.title || 'Docs Preview';
+}

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

@@ -0,0 +1,60 @@
+import { loader } from 'fumadocs-core/source';
+import * as mdxCollections from 'fumadocs-mdx:collections/server';
+
+const docsCollection = (mdxCollections as { docs?: { toFumadocsSource?: () => unknown } }).docs;
+
+if (!docsCollection?.toFumadocsSource) {
+  throw new Error('MDX collections are not ready yet. Please retry in a moment.');
+}
+
+export const source = loader({
+  baseUrl: '/',
+  source: docsCollection.toFumadocsSource() as any,
+});
+
+/**
+ * Get the page tree filtered to a specific session's content.
+ * The content directory has files at {sessionId}/{slug}.mdx,
+ * so the page tree has top-level folders per session.
+ */
+export function getSessionPageTree(sessionId: string) {
+  const fullTree = source.getPageTree();
+  const children = Array.isArray(fullTree.children) ? fullTree.children : [];
+
+  // Find the root folder matching this session ID
+  const sessionFolder = children.find((child: any) => {
+    if (child?.type !== 'folder') return false;
+    // The folder's URL or name should match the session ID
+    const urls = collectUrls(child);
+    for (const url of urls) {
+      const firstSegment = url.replace(/^\/+/, '').split('/')[0];
+      if (firstSegment === sessionId) return true;
+    }
+    return false;
+  }) as any;
+
+  if (sessionFolder && Array.isArray(sessionFolder.children)) {
+    return { ...fullTree, children: sessionFolder.children };
+  }
+
+  // Fallback: filter children by URL prefix
+  const filtered = children.filter((child: any) => {
+    const urls = collectUrls(child);
+    return urls.some((url: string) => {
+      const segments = url.replace(/^\/+/, '').split('/');
+      return segments[0] === sessionId;
+    });
+  });
+
+  return { ...fullTree, children: filtered };
+}
+
+function collectUrls(node: any, out: string[] = []): string[] {
+  if (!node || typeof node !== 'object') return out;
+  if (typeof node.url === 'string') out.push(node.url);
+  if (node.index && typeof node.index.url === 'string') out.push(node.index.url);
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) collectUrls(child, out);
+  }
+  return out;
+}

package/src/preview-engine/next.config.mjs

@@ -0,0 +1,20 @@
+import { resolve } from 'node:path';
+import { createMDX } from 'fumadocs-mdx/next';
+
+const withMDX = createMDX({
+  configPath: './source.config.ts',
+});
+
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: false,
+  devIndicators: false,
+  turbopack: {
+    root: resolve('..'),
+  },
+  images: {
+    unoptimized: true,
+  },
+};
+
+export default withMDX(config);

package/src/preview-engine/postcss.config.mjs

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};

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

@@ -0,0 +1,26 @@
+import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
+import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
+
+// Content directory: NFS-backed preview_content root.
+// Each session writes to {PREVIEW_CONTENT_DIR}/{sessionId}/.
+// fumadocs scans the entire directory; routes filter by session.
+const contentDir = process.env.PREVIEW_CONTENT_DIR || './content';
+
+export const docs = defineDocs({
+  dir: contentDir,
+  docs: {
+    schema: pageSchema,
+  },
+  meta: {
+    schema: metaSchema,
+  },
+});
+
+export default defineConfig({
+  mdxOptions: {
+    rehypeCodeOptions: ({
+      lazy: false,
+      fallbackLanguage: 'bash',
+    } as any),
+  },
+});

package/src/preview-engine/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "target": "ESNext",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "paths": {
+      "@/*": ["./*"],
+      "fumadocs-mdx:collections/*": [".source/*"]
+    },
+    "plugins": [{ "name": "next" }]
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}