@zenithbuild/cli 0.7.5 → 0.7.7

package/dist/preview.js

@@ -3,1123 +3,11 @@
 // ---------------------------------------------------------------------------
 // Preview server with manifest-driven route resolution.
 //
-// - Serves /dist assets directly.
-// - Resolves static and dynamic page routes via router-manifest.json.
-// - Executes non-prerender <script server> blocks per request and injects
-//   serialized SSR payload via an inline script (`window.__zenith_ssr_data`).
+// This file is intentionally a composition facade. Implementation details
+// live in ./preview/* modules.
 // ---------------------------------------------------------------------------
-import { spawn } from 'node:child_process';
-import { createServer } from 'node:http';
-import { access, readFile } from 'node:fs/promises';
-import { extname, join, normalize, resolve, sep, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { appLocalRedirectLocation, imageEndpointPath, normalizeBasePath, routeCheckPath, stripBasePath } from './base-path.js';
-import { resolveBuildAdapter } from './adapters/resolve-adapter.js';
-import { isConfigKeyExplicit, isLoadedConfig, loadConfig, validateConfig } from './config.js';
-import { materializeImageMarkup } from './images/materialize.js';
-import { createImageRuntimePayload, injectImageRuntimePayload } from './images/payload.js';
-import { handleImageRequest } from './images/service.js';
-import { readRequestBodyBuffer } from './request-body.js';
-import { createTrustedOriginResolver } from './request-origin.js';
-import { buildResourceResponseDescriptor } from './resource-response.js';
-import { loadResourceRouteManifest } from './resource-manifest.js';
-import { supportsTargetRouteCheck } from './route-check-support.js';
-import { clientFacingRouteMessage, defaultRouteDenyMessage, logServerException, sanitizeRouteResult } from './server-error.js';
-import { createSilentLogger } from './ui/logger.js';
-import { compareRouteSpecificity, matchRoute as matchManifestRoute, resolveRequestRoute } from './server/resolve-request-route.js';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MIME_TYPES = {
-    '.html': 'text/html',
-    '.js': 'application/javascript',
-    '.css': 'text/css',
-    '.json': 'application/json',
-    '.png': 'image/png',
-    '.jpeg': 'image/jpeg',
-    '.jpg': 'image/jpeg',
-    '.svg': 'image/svg+xml',
-    '.webp': 'image/webp',
-    '.avif': 'image/avif',
-    '.gif': 'image/gif'
-};
-const IMAGE_RUNTIME_TAG_RE = /<script\b[^>]*\bid=(["'])zenith-image-runtime\1[^>]*>[\s\S]*?<\/script>/i;
-function appendSetCookieHeaders(headers, setCookies = []) {
-    if (Array.isArray(setCookies) && setCookies.length > 0) {
-        headers['Set-Cookie'] = setCookies.slice();
-    }
-    return headers;
-}
-const SERVER_SCRIPT_RUNNER = String.raw `
-import vm from 'node:vm';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
-
-const source = process.env.ZENITH_SERVER_SOURCE || '';
-const sourcePath = process.env.ZENITH_SERVER_SOURCE_PATH || '';
-const params = JSON.parse(process.env.ZENITH_SERVER_PARAMS || '{}');
-const requestUrl = process.env.ZENITH_SERVER_REQUEST_URL || 'http://localhost/';
-const requestMethod = String(process.env.ZENITH_SERVER_REQUEST_METHOD || 'GET').toUpperCase();
-const requestHeaders = JSON.parse(process.env.ZENITH_SERVER_REQUEST_HEADERS || '{}');
-const routePattern = process.env.ZENITH_SERVER_ROUTE_PATTERN || '';
-const routeFile = process.env.ZENITH_SERVER_ROUTE_FILE || sourcePath || '';
-const routeId = process.env.ZENITH_SERVER_ROUTE_ID || routePattern || '';
-const routeKind = process.env.ZENITH_SERVER_ROUTE_KIND || 'page';
-const guardOnly = process.env.ZENITH_SERVER_GUARD_ONLY === '1';
-
-if (!source.trim()) {
-  process.stdout.write('null');
-  process.exit(0);
-}
-
-let cachedTypeScript = undefined;
-async function loadTypeScript() {
-  if (cachedTypeScript !== undefined) {
-    return cachedTypeScript;
-  }
-  try {
-    const mod = await import('typescript');
-    cachedTypeScript = mod.default || mod;
-  } catch {
-    cachedTypeScript = null;
-  }
-  return cachedTypeScript;
-}
-
-async function transpileIfNeeded(filename, code) {
-  const lower = String(filename || '').toLowerCase();
-  const isTs =
-    lower.endsWith('.ts') ||
-    lower.endsWith('.tsx') ||
-    lower.endsWith('.mts') ||
-    lower.endsWith('.cts');
-  if (!isTs) {
-    return code;
-  }
-  const ts = await loadTypeScript();
-  if (!ts || typeof ts.transpileModule !== 'function') {
-    throw new Error('[zenith-preview] TypeScript is required to execute server modules that import .ts files');
-  }
-  const output = ts.transpileModule(code, {
-    fileName: filename || 'server-script.ts',
-    compilerOptions: {
-      target: ts.ScriptTarget.ES2022,
-      module: ts.ModuleKind.ESNext,
-      moduleResolution: ts.ModuleResolutionKind.NodeNext
-    },
-    reportDiagnostics: false
-  });
-  return output.outputText;
-}
-
-async function exists(filePath) {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function resolveRelativeSpecifier(specifier, parentIdentifier) {
-  let basePath = sourcePath;
-  if (parentIdentifier && parentIdentifier.startsWith('file:')) {
-    basePath = fileURLToPath(parentIdentifier);
-  }
-
-  const baseDir = basePath ? path.dirname(basePath) : process.cwd();
-  const candidateBase = specifier.startsWith('file:')
-    ? fileURLToPath(specifier)
-    : path.resolve(baseDir, specifier);
-
-  const candidates = [];
-  if (path.extname(candidateBase)) {
-    candidates.push(candidateBase);
-  } else {
-    candidates.push(candidateBase);
-    candidates.push(candidateBase + '.ts');
-    candidates.push(candidateBase + '.tsx');
-    candidates.push(candidateBase + '.mts');
-    candidates.push(candidateBase + '.cts');
-    candidates.push(candidateBase + '.js');
-    candidates.push(candidateBase + '.mjs');
-    candidates.push(candidateBase + '.cjs');
-    candidates.push(path.join(candidateBase, 'index.ts'));
-    candidates.push(path.join(candidateBase, 'index.tsx'));
-    candidates.push(path.join(candidateBase, 'index.mts'));
-    candidates.push(path.join(candidateBase, 'index.cts'));
-    candidates.push(path.join(candidateBase, 'index.js'));
-    candidates.push(path.join(candidateBase, 'index.mjs'));
-    candidates.push(path.join(candidateBase, 'index.cjs'));
-  }
-
-  for (const candidate of candidates) {
-    if (await exists(candidate)) {
-      return pathToFileURL(candidate).href;
-    }
-  }
-
-  throw new Error(
-    '[zenith-preview] Cannot resolve server import "' + specifier + '" from "' + (basePath || '<inline>') + '"'
-  );
-}
-
-function isRelativeSpecifier(specifier) {
-  return (
-    specifier.startsWith('./') ||
-    specifier.startsWith('../') ||
-    specifier.startsWith('/') ||
-    specifier.startsWith('file:')
-  );
-}
-
-const safeRequestHeaders =
-  requestHeaders && typeof requestHeaders === 'object'
-    ? { ...requestHeaders }
-    : {};
-function parseCookies(rawCookieHeader) {
-  const out = Object.create(null);
-  const raw = String(rawCookieHeader || '');
-  if (!raw) return out;
-  const pairs = raw.split(';');
-  for (let i = 0; i < pairs.length; i++) {
-    const part = pairs[i];
-    const eq = part.indexOf('=');
-    if (eq <= 0) continue;
-    const key = part.slice(0, eq).trim();
-    if (!key) continue;
-    const value = part.slice(eq + 1).trim();
-    try {
-      out[key] = decodeURIComponent(value);
-    } catch {
-      out[key] = value;
-    }
-  }
-  return out;
-}
-const cookieHeader = typeof safeRequestHeaders.cookie === 'string'
-  ? safeRequestHeaders.cookie
-  : '';
-const requestCookies = parseCookies(cookieHeader);
-
-function ctxAllow() {
-  return { kind: 'allow' };
-}
-function ctxRedirect(location, status = 302) {
-  return {
-    kind: 'redirect',
-    location: String(location || ''),
-    status: Number.isInteger(status) ? status : 302
-  };
-}
-function ctxDeny(status = 403, message = undefined) {
-  return {
-    kind: 'deny',
-    status: Number.isInteger(status) ? status : 403,
-    message: typeof message === 'string' ? message : undefined
-  };
-}
-function ctxInvalid(payload, status = 400) {
-  return {
-    kind: 'invalid',
-    data: payload,
-    status: Number.isInteger(status) ? status : 400
-  };
-}
-function ctxData(payload) {
-  return {
-    kind: 'data',
-    data: payload
-  };
-}
-function ctxJson(payload, status = 200) {
-  return {
-    kind: 'json',
-    data: payload,
-    status: Number.isInteger(status) ? status : 200
-  };
-}
-function ctxText(body, status = 200) {
-  return {
-    kind: 'text',
-    body: typeof body === 'string' ? body : String(body ?? ''),
-    status: Number.isInteger(status) ? status : 200
-  };
-}
-
-async function readStdinBuffer() {
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-  }
-  return Buffer.concat(chunks);
-}
-
-const requestInit = {
-  method: requestMethod,
-  headers: new Headers(safeRequestHeaders)
-};
-const requestBodyBuffer =
-  requestMethod !== 'GET' && requestMethod !== 'HEAD'
-    ? await readStdinBuffer()
-    : Buffer.alloc(0);
-if (requestMethod !== 'GET' && requestMethod !== 'HEAD' && requestBodyBuffer.length > 0) {
-  requestInit.body = requestBodyBuffer;
-  requestInit.duplex = 'half';
-}
-const requestSnapshot = new Request(requestUrl, requestInit);
-const routeParams = { ...params };
-const routeMeta = {
-  id: routeId,
-  pattern: routePattern,
-  file: routeFile ? path.relative(process.cwd(), routeFile) : ''
-};
-const routeContext = {
-  params: routeParams,
-  url: new URL(requestUrl),
-  headers: { ...safeRequestHeaders },
-  cookies: requestCookies,
-  request: requestSnapshot,
-  method: requestMethod,
-  route: routeMeta,
-  env: {},
-  action: null,
-  allow: ctxAllow,
-  redirect: ctxRedirect,
-  deny: ctxDeny,
-  invalid: ctxInvalid,
-  data: ctxData,
-  json: ctxJson,
-  text: ctxText
-};
-
-const context = vm.createContext({
-  params: routeParams,
-  ctx: routeContext,
-  fetch: globalThis.fetch,
-  Blob: globalThis.Blob,
-  File: globalThis.File,
-  FormData: globalThis.FormData,
-  Headers: globalThis.Headers,
-  Request: globalThis.Request,
-  Response: globalThis.Response,
-  TextEncoder: globalThis.TextEncoder,
-  TextDecoder: globalThis.TextDecoder,
-  URL,
-  URLSearchParams,
-  Buffer,
-  console,
-  process,
-  setTimeout,
-  clearTimeout,
-  setInterval,
-  clearInterval
-});
-
-const moduleCache = new Map();
-const syntheticModuleCache = new Map();
-
-async function createSyntheticModule(specifier) {
-  if (syntheticModuleCache.has(specifier)) {
-    return syntheticModuleCache.get(specifier);
-  }
-
-  const ns = await import(specifier);
-  const exportNames = Object.keys(ns);
-  const module = new vm.SyntheticModule(
-    exportNames,
-    function() {
-      for (const key of exportNames) {
-        this.setExport(key, ns[key]);
-      }
-    },
-    { context }
-  );
-  await module.link(() => {
-    throw new Error(
-      '[zenith-preview] synthetic modules cannot contain nested imports: ' + specifier
-    );
-  });
-  syntheticModuleCache.set(specifier, module);
-  return module;
-}
-
-async function loadFileModule(moduleUrl) {
-  if (moduleCache.has(moduleUrl)) {
-    return moduleCache.get(moduleUrl);
-  }
-  const modulePromise = (async () => {
-    const filename = fileURLToPath(moduleUrl);
-    let code = await fs.readFile(filename, 'utf8');
-    code = await transpileIfNeeded(filename, code);
-    const module = new vm.SourceTextModule(code, {
-      context,
-      identifier: moduleUrl,
-      initializeImportMeta(meta) {
-        meta.url = moduleUrl;
-      }
-    });
-
-    await module.link((specifier, referencingModule) => {
-      return linkModule(specifier, referencingModule.identifier);
-    });
-    return module;
-  })();
-
-  moduleCache.set(moduleUrl, modulePromise);
-  try {
-    return await modulePromise;
-  } catch (error) {
-    moduleCache.delete(moduleUrl);
-    throw error;
-  }
-}
-
-async function linkModule(specifier, parentIdentifier) {
-  if (!isRelativeSpecifier(specifier)) {
-    return createSyntheticModule(specifier);
-  }
-  const resolvedUrl = await resolveRelativeSpecifier(specifier, parentIdentifier);
-  return loadFileModule(resolvedUrl);
-}
-
-const allowed = new Set(['data', 'load', 'guard', 'action', 'ssr_data', 'props', 'ssr', 'prerender', 'exportPaths']);
-const prelude = "const params = globalThis.params;\n" +
-  "const ctx = globalThis.ctx;\n" +
-  "import { download, resolveRouteResult } from 'zenith:server-contract';\n" +
-  "import { attachRouteAuth } from 'zenith:route-auth';\n" +
-  "ctx.download = download;\n" +
-  "globalThis.resolveRouteResult = resolveRouteResult;\n" +
-  "globalThis.attachRouteAuth = attachRouteAuth;\n";
-const entryIdentifier = sourcePath
-  ? pathToFileURL(sourcePath).href
-  : 'zenith:server-script';
-const entryTranspileFilename = sourcePath && sourcePath.toLowerCase().endsWith('.zen')
-  ? sourcePath.replace(/\.zen$/i, '.ts')
-  : (sourcePath || 'server-script.ts');
-
-const entryCode = await transpileIfNeeded(entryTranspileFilename, prelude + source);
-const entryModule = new vm.SourceTextModule(entryCode, {
-  context,
-  identifier: entryIdentifier,
-  initializeImportMeta(meta) {
-    meta.url = entryIdentifier;
-  }
-});
-
-moduleCache.set(entryIdentifier, entryModule);
-await entryModule.link((specifier, referencingModule) => {
-  if (specifier === 'zenith:server-contract') {
-    const defaultPath = path.join(process.cwd(), 'node_modules', '@zenithbuild', 'cli', 'src', 'server-contract.js');
-    const configuredPath = process.env.ZENITH_SERVER_CONTRACT_PATH || '';
-    const contractUrl = pathToFileURL(configuredPath || defaultPath).href;
-    if (configuredPath) {
-      return loadFileModule(contractUrl);
-    }
-    return loadFileModule(contractUrl).catch(() =>
-      loadFileModule(pathToFileURL(defaultPath).href)
-    );
-  }
-  if (specifier === 'zenith:route-auth') {
-    const defaultPath = path.join(process.cwd(), 'node_modules', '@zenithbuild', 'cli', 'src', 'auth', 'route-auth.js');
-    const configuredPath = process.env.ZENITH_SERVER_ROUTE_AUTH_PATH || '';
-    const authUrl = pathToFileURL(configuredPath || defaultPath).href;
-    if (configuredPath) {
-      return loadFileModule(authUrl);
-    }
-    return loadFileModule(authUrl).catch(() =>
-      loadFileModule(pathToFileURL(defaultPath).href)
-    );
-  }
-  return linkModule(specifier, referencingModule.identifier);
-});
-await entryModule.evaluate();
-context.attachRouteAuth(routeContext, {
-  requestUrl: routeContext.url,
-  guardOnly,
-  redirect: ctxRedirect,
-  deny: ctxDeny
-});
-
-const namespaceKeys = Object.keys(entryModule.namespace);
-for (const key of namespaceKeys) {
-  if (!allowed.has(key)) {
-    throw new Error('[zenith-preview] unsupported server export "' + key + '"');
-  }
-}
-
-const exported = entryModule.namespace;
-try {
-  const resolved = await context.resolveRouteResult({
-    exports: exported,
-    ctx: context.ctx,
-    filePath: sourcePath || 'server_script',
-    guardOnly: guardOnly,
-    routeKind: routeKind
-  });
-
-  process.stdout.write(JSON.stringify(resolved || null));
-} catch (error) {
-  const message = error instanceof Error
-    ? (typeof error.stack === 'string' && error.stack.length > 0 ? error.stack : error.message)
-    : String(error);
-  process.stderr.write('[Zenith:Server] preview route execution failed\\n' + message + '\\n');
-  process.stdout.write(
-    JSON.stringify({
-      __zenith_error: {
-        status: 500,
-        code: 'LOAD_FAILED'
-      }
-    })
-  );
-}
-`;
-/**
- * Create and start a preview server.
- *
- * @param {{ distDir: string, port?: number, host?: string, logger?: object | null, config?: object, projectRoot?: string }} options
- * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
- */
-export async function createPreviewServer(options) {
-    const resolvedProjectRoot = options?.projectRoot ? resolve(options.projectRoot) : resolve(options.distDir, '..');
-    const loadedConfig = await loadConfig(resolvedProjectRoot);
-    const resolvedConfig = options?.config && typeof options.config === 'object'
-        ? (() => {
-            const overrideConfig = isLoadedConfig(options.config)
-                ? options.config
-                : validateConfig(options.config);
-            const mergedConfig = { ...loadedConfig };
-            for (const key of Object.keys(overrideConfig)) {
-                if (isConfigKeyExplicit(overrideConfig, key)) {
-                    mergedConfig[key] = overrideConfig[key];
-                }
-            }
-            return mergedConfig;
-        })()
-        : loadedConfig;
-    const { distDir, port = 4000, host = '127.0.0.1', logger: providedLogger = null } = options;
-    const projectRoot = resolvedProjectRoot;
-    const config = resolvedConfig;
-    const logger = providedLogger || createSilentLogger();
-    const verboseLogging = logger.mode?.logLevel === 'verbose';
-    const configuredBasePath = normalizeBasePath(config.basePath || '/');
-    const resolvedTarget = resolveBuildAdapter(config).target;
-    const routeCheckEnabled = supportsTargetRouteCheck(resolvedTarget);
-    const isStaticExportTarget = resolvedTarget === 'static-export';
-    let actualPort = port;
-    const resolveServerOrigin = createTrustedOriginResolver({
-        host,
-        getPort: () => actualPort,
-        label: 'preview server'
-    });
-    async function loadImageManifest() {
-        try {
-            const manifestRaw = await readFile(join(distDir, '_zenith', 'image', 'manifest.json'), 'utf8');
-            const parsed = JSON.parse(manifestRaw);
-            return parsed && typeof parsed === 'object' ? parsed : {};
-        }
-        catch {
-            return {};
-        }
-    }
-    const server = createServer(async (req, res) => {
-        const url = new URL(req.url, resolveServerOrigin());
-        const { basePath, pageRoutes, resourceRoutes } = await loadRouteSurfaceState(distDir, configuredBasePath);
-        const canonicalPath = stripBasePath(url.pathname, basePath);
-        try {
-            if (url.pathname === routeCheckPath(basePath)) {
-                if (!routeCheckEnabled) {
-                    res.writeHead(501, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
-                    res.end(JSON.stringify({ error: 'route_check_unsupported' }));
-                    return;
-                }
-                // Security: Require explicitly designated header to prevent public oracle probing
-                if (req.headers['x-zenith-route-check'] !== '1') {
-                    res.writeHead(403, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'forbidden', message: 'invalid request context' }));
-                    return;
-                }
-                const targetPath = String(url.searchParams.get('path') || '/');
-                // Security: Prevent protocol/domain injection in path
-                if (targetPath.includes('://') || targetPath.startsWith('//') || /[\r\n]/.test(targetPath)) {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'invalid_path_format' }));
-                    return;
-                }
-                const targetUrl = new URL(targetPath, url.origin);
-                if (targetUrl.origin !== url.origin) {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'external_route_evaluation_forbidden' }));
-                    return;
-                }
-                const canonicalTargetPath = stripBasePath(targetUrl.pathname, basePath);
-                if (canonicalTargetPath === null) {
-                    res.writeHead(404, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'route_not_found' }));
-                    return;
-                }
-                const canonicalTargetUrl = new URL(targetUrl.toString());
-                canonicalTargetUrl.pathname = canonicalTargetPath;
-                const resolvedCheck = resolveRequestRoute(canonicalTargetUrl, pageRoutes);
-                if (!resolvedCheck.matched || !resolvedCheck.route) {
-                    res.writeHead(404, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'route_not_found' }));
-                    return;
-                }
-                const checkResult = await executeServerRoute({
-                    source: resolvedCheck.route.server_script || '',
-                    sourcePath: resolvedCheck.route.server_script_path || '',
-                    params: resolvedCheck.params,
-                    requestUrl: targetUrl.toString(),
-                    requestMethod: req.method || 'GET',
-                    requestHeaders: req.headers,
-                    routePattern: resolvedCheck.route.path,
-                    routeFile: resolvedCheck.route.server_script_path || '',
-                    routeId: resolvedCheck.route.route_id || routeIdFromSourcePath(resolvedCheck.route.server_script_path || ''),
-                    guardOnly: true
-                });
-                // Security: Enforce relative or same-origin redirects
-                if (checkResult && checkResult.result && checkResult.result.kind === 'redirect') {
-                    const loc = appLocalRedirectLocation(checkResult.result.location || '/', basePath);
-                    checkResult.result.location = loc;
-                    if (loc.includes('://') || loc.startsWith('//')) {
-                        try {
-                            const parsedLoc = new URL(loc);
-                            if (parsedLoc.origin !== targetUrl.origin) {
-                                checkResult.result.location = appLocalRedirectLocation('/', basePath);
-                            }
-                        }
-                        catch {
-                            checkResult.result.location = appLocalRedirectLocation('/', basePath);
-                        }
-                    }
-                }
-                res.writeHead(200, {
-                    'Content-Type': 'application/json',
-                    'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate',
-                    'Pragma': 'no-cache',
-                    'Expires': '0',
-                    'Vary': 'Cookie'
-                });
-                res.end(JSON.stringify({
-                    result: sanitizeRouteResult(checkResult?.result || checkResult),
-                    routeId: resolvedCheck.route.route_id || '',
-                    to: targetUrl.toString()
-                }));
-                return;
-            }
-            if (url.pathname === imageEndpointPath(basePath)) {
-                if (isStaticExportTarget) {
-                    throw new Error('not found');
-                }
-                await handleImageRequest(req, res, {
-                    requestUrl: url,
-                    projectRoot,
-                    config: config.images
-                });
-                return;
-            }
-            if (canonicalPath === null) {
-                throw new Error('not found');
-            }
-            if (extname(canonicalPath) && extname(canonicalPath) !== '.html') {
-                const staticPath = isStaticExportTarget
-                    ? resolveWithinDist(distDir, url.pathname)
-                    : resolveWithinDist(distDir, canonicalPath);
-                if (!staticPath || !(await fileExists(staticPath))) {
-                    throw new Error('not found');
-                }
-                const content = await readFile(staticPath);
-                const mime = MIME_TYPES[extname(staticPath)] || 'application/octet-stream';
-                res.writeHead(200, { 'Content-Type': mime });
-                res.end(content);
-                return;
-            }
-            if (isStaticExportTarget) {
-                const directHtmlPath = toStaticFilePath(distDir, url.pathname);
-                if (!directHtmlPath || !(await fileExists(directHtmlPath))) {
-                    throw new Error('not found');
-                }
-                const html = await readFile(directHtmlPath, 'utf8');
-                res.writeHead(200, { 'Content-Type': 'text/html' });
-                res.end(html);
-                return;
-            }
-            const canonicalUrl = new URL(url.toString());
-            canonicalUrl.pathname = canonicalPath;
-            const resolvedResource = resolveRequestRoute(canonicalUrl, resourceRoutes);
-            if (resolvedResource.matched && resolvedResource.route) {
-                const requestMethod = req.method || 'GET';
-                const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
-                    ? null
-                    : await readRequestBodyBuffer(req);
-                const execution = await executeServerRoute({
-                    source: resolvedResource.route.server_script || '',
-                    sourcePath: resolvedResource.route.server_script_path || '',
-                    params: resolvedResource.params,
-                    requestUrl: url.toString(),
-                    requestMethod,
-                    requestHeaders: req.headers,
-                    requestBodyBuffer,
-                    routePattern: resolvedResource.route.path,
-                    routeFile: resolvedResource.route.server_script_path || '',
-                    routeId: resolvedResource.route.route_id || routeIdFromSourcePath(resolvedResource.route.server_script_path || ''),
-                    routeKind: 'resource'
-                });
-                const descriptor = buildResourceResponseDescriptor(execution?.result, basePath, Array.isArray(execution?.setCookies) ? execution.setCookies : []);
-                res.writeHead(descriptor.status, appendSetCookieHeaders(descriptor.headers, descriptor.setCookies));
-                if ((req.method || 'GET').toUpperCase() === 'HEAD') {
-                    res.end();
-                    return;
-                }
-                res.end(descriptor.body);
-                return;
-            }
-            const resolved = resolveRequestRoute(canonicalUrl, pageRoutes);
-            let htmlPath = null;
-            if (resolved.matched && resolved.route) {
-                if (verboseLogging) {
-                    logger.router(`${req.method || 'GET'} ${url.pathname} -> ${resolved.route.path} params=${JSON.stringify(resolved.params)}`);
-                }
-                const output = resolved.route.output.startsWith('/')
-                    ? resolved.route.output.slice(1)
-                    : resolved.route.output;
-                htmlPath = resolveWithinDist(distDir, output);
-            }
-            else {
-                htmlPath = toStaticFilePath(distDir, url.pathname);
-            }
-            if (!htmlPath || !(await fileExists(htmlPath))) {
-                throw new Error('not found');
-            }
-            let ssrPayload = null;
-            let routeExecution = null;
-            if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
-                try {
-                    const requestMethod = req.method || 'GET';
-                    const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
-                        ? null
-                        : await readRequestBodyBuffer(req);
-                    routeExecution = await executeServerRoute({
-                        source: resolved.route.server_script,
-                        sourcePath: resolved.route.server_script_path || '',
-                        params: resolved.params,
-                        requestUrl: url.toString(),
-                        requestMethod,
-                        requestHeaders: req.headers,
-                        requestBodyBuffer,
-                        routePattern: resolved.route.path,
-                        routeFile: resolved.route.server_script_path || '',
-                        routeId: resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '')
-                    });
-                }
-                catch (error) {
-                    logServerException('preview server route execution failed', error);
-                    ssrPayload = {
-                        __zenith_error: {
-                            status: 500,
-                            code: 'LOAD_FAILED',
-                            message: error instanceof Error ? error.message : String(error || '')
-                        }
-                    };
-                }
-                const trace = routeExecution?.trace || { guard: 'none', action: 'none', load: 'none' };
-                const routeId = resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '');
-                const setCookies = Array.isArray(routeExecution?.setCookies) ? routeExecution.setCookies : [];
-                if (verboseLogging) {
-                    logger.router(`${routeId} guard=${trace.guard} action=${trace.action} load=${trace.load}`);
-                }
-                const result = routeExecution?.result;
-                if (result && result.kind === 'redirect') {
-                    const status = Number.isInteger(result.status) ? result.status : 302;
-                    res.writeHead(status, appendSetCookieHeaders({
-                        Location: appLocalRedirectLocation(result.location, basePath),
-                        'Cache-Control': 'no-store'
-                    }, setCookies));
-                    res.end('');
-                    return;
-                }
-                if (result && result.kind === 'deny') {
-                    const status = Number.isInteger(result.status) ? result.status : 403;
-                    res.writeHead(status, appendSetCookieHeaders({ 'Content-Type': 'text/plain; charset=utf-8' }, setCookies));
-                    res.end(clientFacingRouteMessage(status, result.message));
-                    return;
-                }
-                if (result && result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
-                    ssrPayload = result.data;
-                }
-            }
-            let html = await readFile(htmlPath, 'utf8');
-            if (resolved.matched) {
-                html = await materializeImageMarkup({
-                    html,
-                    payload: createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath),
-                    imageMaterialization: Array.isArray(resolved.route?.image_materialization)
-                        ? resolved.route.image_materialization
-                        : []
-                });
-            }
-            if (ssrPayload) {
-                html = injectSsrPayload(html, ssrPayload);
-            }
-            if (!IMAGE_RUNTIME_TAG_RE.test(html)) {
-                html = injectImageRuntimePayload(html, createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath));
-            }
-            res.writeHead(Number.isInteger(routeExecution?.status) ? routeExecution.status : 200, appendSetCookieHeaders({
-                'Content-Type': 'text/html'
-            }, Array.isArray(routeExecution?.setCookies) ? routeExecution.setCookies : []));
-            res.end(html);
-        }
-        catch {
-            res.writeHead(404, { 'Content-Type': 'text/plain' });
-            res.end('404 Not Found');
-        }
-    });
-    return new Promise((resolveServer) => {
-        server.listen(port, host, () => {
-            actualPort = server.address().port;
-            resolveServer({
-                server,
-                port: actualPort,
-                close: () => {
-                    server.close();
-                }
-            });
-        });
-    });
-}
-/**
- * @typedef {{
- *   path: string;
- *   output: string;
- *   server_script?: string | null;
- *   server_script_path?: string | null;
- *   prerender?: boolean;
- *   route_id?: string;
- *   pattern?: string;
- *   params_shape?: Record<string, string>;
- *   has_guard?: boolean;
- *   has_load?: boolean;
- *   guard_module_ref?: string | null;
- *   load_module_ref?: string | null;
- * }} PreviewRoute
- */
-/**
- * @param {string} distDir
- * @returns {Promise<PreviewRoute[]>}
- */
-export async function loadRouteManifest(distDir) {
-    const state = await loadRouteSurfaceState(distDir, '/');
-    return state.pageRoutes;
-}
-export async function loadRouteSurfaceState(distDir, fallbackBasePath = '/') {
-    const manifestPath = join(distDir, 'assets', 'router-manifest.json');
-    const resourceState = await loadResourceRouteManifest(distDir, normalizeBasePath(fallbackBasePath || '/'));
-    try {
-        const source = await readFile(manifestPath, 'utf8');
-        const parsed = JSON.parse(source);
-        const routes = Array.isArray(parsed?.routes) ? parsed.routes : [];
-        const basePath = normalizeBasePath(parsed?.base_path || resourceState.basePath || fallbackBasePath || '/');
-        return {
-            basePath,
-            pageRoutes: routes
-                .filter((entry) => entry &&
-                typeof entry === 'object' &&
-                typeof entry.path === 'string' &&
-                typeof entry.output === 'string')
-                .sort((a, b) => compareRouteSpecificity(a.path, b.path)),
-            resourceRoutes: Array.isArray(resourceState.routes) ? resourceState.routes : []
-        };
-    }
-    catch {
-        return {
-            basePath: normalizeBasePath(resourceState.basePath || fallbackBasePath || '/'),
-            pageRoutes: [],
-            resourceRoutes: Array.isArray(resourceState.routes) ? resourceState.routes : []
-        };
-    }
-}
-export const matchRoute = matchManifestRoute;
-/**
- * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, requestBodyBuffer?: Buffer | null, routePattern?: string, routeFile?: string, routeId?: string, routeKind?: 'page' | 'resource' }} input
- * @returns {Promise<{ result: { kind: string, [key: string]: unknown }, trace: { guard: string, action: string, load: string }, status?: number, setCookies?: string[] }>}
- */
-export async function executeServerRoute({ source, sourcePath, params, requestUrl, requestMethod, requestHeaders, requestBodyBuffer, routePattern, routeFile, routeId, routeKind = 'page', guardOnly = false }) {
-    if (!source || !String(source).trim()) {
-        return {
-            result: { kind: 'data', data: {} },
-            trace: { guard: 'none', action: 'none', load: 'none' }
-        };
-    }
-    const payload = await spawnNodeServerRunner({
-        source,
-        sourcePath,
-        params,
-        requestUrl: requestUrl || 'http://localhost/',
-        requestMethod: requestMethod || 'GET',
-        requestHeaders: sanitizeRequestHeaders(requestHeaders || {}),
-        requestBodyBuffer: Buffer.isBuffer(requestBodyBuffer) ? requestBodyBuffer : null,
-        routePattern: routePattern || '',
-        routeFile: routeFile || sourcePath || '',
-        routeId: routeId || routeIdFromSourcePath(sourcePath || ''),
-        routeKind,
-        guardOnly
-    });
-    if (payload === null || payload === undefined) {
-        return {
-            result: { kind: 'data', data: {} },
-            trace: { guard: 'none', action: 'none', load: 'none' }
-        };
-    }
-    if (typeof payload !== 'object' || Array.isArray(payload)) {
-        throw new Error('[zenith-preview] server script payload must be an object');
-    }
-    const errorEnvelope = payload.__zenith_error;
-    if (errorEnvelope && typeof errorEnvelope === 'object') {
-        return {
-            result: {
-                kind: 'deny',
-                status: 500,
-                message: defaultRouteDenyMessage(500)
-            },
-            trace: { guard: 'none', action: 'none', load: 'deny' }
-        };
-    }
-    const result = payload.result;
-    const trace = payload.trace;
-    if (result && typeof result === 'object' && !Array.isArray(result) && typeof result.kind === 'string') {
-        return {
-            result,
-            trace: trace && typeof trace === 'object'
-                ? {
-                    guard: String(trace.guard || 'none'),
-                    action: String(trace.action || 'none'),
-                    load: String(trace.load || 'none')
-                }
-                : { guard: 'none', action: 'none', load: 'none' },
-            status: Number.isInteger(payload.status) ? payload.status : undefined,
-            setCookies: Array.isArray(payload.setCookies)
-                ? payload.setCookies.filter((value) => typeof value === 'string' && value.length > 0)
-                : []
-        };
-    }
-    return {
-        result: {
-            kind: 'data',
-            data: payload
-        },
-        trace: { guard: 'none', action: 'none', load: 'data' }
-    };
-}
-/**
- * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, routePattern?: string, routeFile?: string, routeId?: string }} input
- * @returns {Promise<Record<string, unknown> | null>}
- */
-export async function executeServerScript(input) {
-    const execution = await executeServerRoute(input);
-    const result = execution?.result;
-    if (!result || typeof result !== 'object') {
-        return null;
-    }
-    if (result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
-        return result.data;
-    }
-    if (result.kind === 'redirect') {
-        return {
-            __zenith_error: {
-                status: Number.isInteger(result.status) ? result.status : 302,
-                code: 'REDIRECT',
-                message: `Redirect to ${String(result.location || '')}`
-            }
-        };
-    }
-    if (result.kind === 'deny') {
-        const status = Number.isInteger(result.status) ? result.status : 403;
-        return {
-            __zenith_error: {
-                status,
-                code: status >= 500 ? 'LOAD_FAILED' : (status === 404 ? 'NOT_FOUND' : 'ACCESS_DENIED'),
-                message: clientFacingRouteMessage(status, result.message)
-            }
-        };
-    }
-    return {};
-}
-/**
- * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl: string, requestMethod: string, requestHeaders: Record<string, string>, requestBodyBuffer?: Buffer | null, routePattern: string, routeFile: string, routeId: string, routeKind?: 'page' | 'resource' }} input
- * @returns {Promise<unknown>}
- */
-function spawnNodeServerRunner(input) {
-    return new Promise((resolvePromise, rejectPromise) => {
-        const child = spawn(process.execPath, ['--experimental-vm-modules', '--input-type=module', '-e', SERVER_SCRIPT_RUNNER], {
-            env: {
-                ...process.env,
-                ZENITH_SERVER_SOURCE: input.source,
-                ZENITH_SERVER_SOURCE_PATH: input.sourcePath || '',
-                ZENITH_SERVER_PARAMS: JSON.stringify(input.params || {}),
-                ZENITH_SERVER_REQUEST_URL: input.requestUrl || 'http://localhost/',
-                ZENITH_SERVER_REQUEST_METHOD: input.requestMethod || 'GET',
-                ZENITH_SERVER_REQUEST_HEADERS: JSON.stringify(input.requestHeaders || {}),
-                ZENITH_SERVER_ROUTE_PATTERN: input.routePattern || '',
-                ZENITH_SERVER_ROUTE_FILE: input.routeFile || input.sourcePath || '',
-                ZENITH_SERVER_ROUTE_ID: input.routeId || '',
-                ZENITH_SERVER_ROUTE_KIND: input.routeKind || 'page',
-                ZENITH_SERVER_GUARD_ONLY: input.guardOnly ? '1' : '',
-                ZENITH_SERVER_CONTRACT_PATH: join(__dirname, 'server-contract.js'),
-                ZENITH_SERVER_ROUTE_AUTH_PATH: join(__dirname, 'auth', 'route-auth.js')
-            },
-            stdio: ['pipe', 'pipe', 'pipe']
-        });
-        const runnerRequestBody = Buffer.isBuffer(input.requestBodyBuffer) ? input.requestBodyBuffer : null;
-        child.stdin.on('error', () => {
-            // ignore broken pipes when the runner exits before consuming stdin
-        });
-        child.stdin.end(runnerRequestBody && runnerRequestBody.length > 0 ? runnerRequestBody : undefined);
-        let stdout = '';
-        let stderr = '';
-        child.stdout.on('data', (chunk) => {
-            stdout += String(chunk);
-        });
-        child.stderr.on('data', (chunk) => {
-            stderr += String(chunk);
-        });
-        child.on('error', (error) => {
-            rejectPromise(error);
-        });
-        child.on('close', (code) => {
-            if (code !== 0) {
-                rejectPromise(new Error(`[zenith-preview] server script execution failed (${code}): ${stderr.trim() || stdout.trim()}`));
-                return;
-            }
-            const stderrOutput = stderr.trim();
-            const internalErrorIndex = stderrOutput.indexOf('[Zenith:Server]');
-            if (internalErrorIndex >= 0) {
-                console.error(stderrOutput.slice(internalErrorIndex).trim());
-            }
-            const raw = stdout.trim();
-            if (!raw || raw === 'null') {
-                resolvePromise(null);
-                return;
-            }
-            try {
-                resolvePromise(JSON.parse(raw));
-            }
-            catch (error) {
-                rejectPromise(new Error(`[zenith-preview] invalid server payload JSON: ${error instanceof Error ? error.message : String(error)}`));
-            }
-        });
-    });
-}
-/**
- * @param {string} html
- * @param {Record<string, unknown>} payload
- * @returns {string}
- */
-export function injectSsrPayload(html, payload) {
-    const serialized = serializeInlineScriptJson(payload);
-    const scriptTag = `<script id="zenith-ssr-data">window.__zenith_ssr_data = ${serialized};</script>`;
-    const existingTagRe = /<script\b[^>]*\bid=(["'])zenith-ssr-data\1[^>]*>[\s\S]*?<\/script>/i;
-    if (existingTagRe.test(html)) {
-        return html.replace(existingTagRe, scriptTag);
-    }
-    const headClose = html.match(/<\/head>/i);
-    if (headClose) {
-        return html.replace(/<\/head>/i, `${scriptTag}</head>`);
-    }
-    const bodyOpen = html.match(/<body\b[^>]*>/i);
-    if (bodyOpen) {
-        return html.replace(bodyOpen[0], `${bodyOpen[0]}${scriptTag}`);
-    }
-    return `${scriptTag}${html}`;
-}
-/**
- * @param {Record<string, unknown>} payload
- * @returns {string}
- */
-function serializeInlineScriptJson(payload) {
-    return JSON.stringify(payload)
-        .replace(/</g, '\\u003C')
-        .replace(/>/g, '\\u003E')
-        .replace(/\//g, '\\u002F')
-        .replace(/\u2028/g, '\\u2028')
-        .replace(/\u2029/g, '\\u2029');
-}
-export function toStaticFilePath(distDir, pathname) {
-    let resolved = pathname;
-    if (resolved === '/') {
-        resolved = '/index.html';
-    }
-    else if (!extname(resolved)) {
-        resolved += '/index.html';
-    }
-    return resolveWithinDist(distDir, resolved);
-}
-export function resolveWithinDist(distDir, requestPath) {
-    let decoded = requestPath;
-    try {
-        decoded = decodeURIComponent(requestPath);
-    }
-    catch {
-        return null;
-    }
-    const normalized = normalize(decoded).replace(/\\/g, '/');
-    const relative = normalized.replace(/^\/+/, '');
-    const root = resolve(distDir);
-    const candidate = resolve(root, relative);
-    if (candidate === root || candidate.startsWith(`${root}${sep}`)) {
-        return candidate;
-    }
-    return null;
-}
-/**
- * @param {Record<string, string | string[] | undefined>} headers
- * @returns {Record<string, string>}
- */
-function sanitizeRequestHeaders(headers) {
-    const out = Object.create(null);
-    const denyExact = new Set(['proxy-authorization', 'set-cookie']);
-    const denyPrefixes = ['x-forwarded-', 'cf-'];
-    for (const [rawKey, rawValue] of Object.entries(headers || {})) {
-        const key = String(rawKey || '').toLowerCase();
-        if (!key)
-            continue;
-        if (denyExact.has(key))
-            continue;
-        if (denyPrefixes.some((prefix) => key.startsWith(prefix)))
-            continue;
-        let value = '';
-        if (Array.isArray(rawValue)) {
-            value = rawValue.filter((entry) => entry !== undefined).map(String).join(', ');
-        }
-        else if (rawValue !== undefined) {
-            value = String(rawValue);
-        }
-        out[key] = value;
-    }
-    return out;
-}
-/**
- * @param {string} sourcePath
- * @returns {string}
- */
-function routeIdFromSourcePath(sourcePath) {
-    const normalized = String(sourcePath || '').replaceAll('\\', '/');
-    const marker = '/pages/';
-    const markerIndex = normalized.lastIndexOf(marker);
-    let routeId = markerIndex >= 0
-        ? normalized.slice(markerIndex + marker.length)
-        : normalized.split('/').pop() || normalized;
-    routeId = routeId.replace(/\.zen$/i, '');
-    if (routeId.endsWith('/index')) {
-        routeId = routeId.slice(0, -('/index'.length));
-    }
-    return routeId || 'index';
-}
-async function fileExists(fullPath) {
-    try {
-        await access(fullPath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+export { createPreviewServer } from './preview/create-preview-server.js';
+export { loadRouteManifest, loadRouteSurfaceState, matchRoute } from './preview/manifest.js';
+export { executeServerRoute, executeServerScript } from './preview/server-runner.js';
+export { injectSsrPayload } from './preview/payload.js';
+export { toStaticFilePath, resolveWithinDist } from './preview/paths.js';