@zenithbuild/cli 0.7.5 → 0.7.7

package/dist/images/payload.js

@@ -18,6 +18,10 @@ function serializeInlineScriptJson(payload) {
         .replace(/\u2029/g, '\\u2029');
 }
 export function injectImageRuntimePayload(html, payload) {
+    // Only inject if the HTML contains Zenith image markers or unsafeHTML
+    if (!/data-zx-(data-zenith-image|unsafeHTML)/.test(html)) {
+        return html;
+    }
     const safePayload = createImageRuntimePayload(payload?.config || {}, payload?.localImages || {}, payload?.mode || 'passthrough', payload?.basePath || '/');
     const globalName = imageRuntimeGlobalName();
     const serialized = serializeInlineScriptJson(safePayload);

package/dist/manifest.js

@@ -16,7 +16,7 @@
 // ---------------------------------------------------------------------------
 import { readFileSync } from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
-import { join, relative, sep, basename, extname, dirname } from 'node:path';
+import { join, relative, sep, basename, extname, dirname, resolve } from 'node:path';
 import { extractServerScript } from './build/server-script.js';
 import { analyzeResourceRouteModule, isResourceRouteFile } from './resource-route-module.js';
 import { composeServerScriptEnvelope, resolveAdjacentServerModules } from './server-script-composition.js';
@@ -47,6 +47,11 @@ import { validateStaticExportPaths } from './static-export-paths.js';
  */
 export async function generateManifest(pagesDir, extension = '.zen', options = {}) {
     const entries = await _scanDir(pagesDir, pagesDir, extension, options.compilerOpts || {});
+    const apiAliasState = _resolveSrcApiAliasState(pagesDir);
+    if (apiAliasState) {
+        const aliasEntries = await _scanResourceDir(apiAliasState.aliasDir, apiAliasState.srcDir);
+        entries.push(...aliasEntries);
+    }
     // Validate: no repeated param names in any single route
     for (const entry of entries) {
         _validateParams(entry.path);
@@ -97,6 +102,46 @@ async function _scanDir(dir, root, ext, compilerOpts) {
     }
     return entries;
 }
+async function _scanResourceDir(dir, root) {
+    /** @type {ManifestEntry[]} */
+    const entries = [];
+    let items;
+    try {
+        items = await readdir(dir);
+    }
+    catch {
+        return entries;
+    }
+    items.sort();
+    for (const item of items) {
+        const fullPath = join(dir, item);
+        const info = await stat(fullPath);
+        if (info.isDirectory()) {
+            const nested = await _scanResourceDir(fullPath, root);
+            entries.push(...nested);
+        }
+        else if (isResourceRouteFile(item)) {
+            entries.push(analyzeResourceRouteModule(fullPath, root));
+        }
+    }
+    return entries;
+}
+function _resolveSrcApiAliasState(pagesDir) {
+    const resolvedPagesDir = resolve(pagesDir);
+    const srcDir = dirname(resolvedPagesDir);
+    if (basename(srcDir) !== 'src') {
+        return null;
+    }
+    const aliasDir = join(srcDir, 'api');
+    if (aliasDir === resolvedPagesDir ||
+        aliasDir.startsWith(`${resolvedPagesDir}${sep}`)) {
+        return null;
+    }
+    return {
+        aliasDir,
+        srcDir
+    };
+}
 function buildPageManifestEntry({ fullPath, root, routePath, compilerOpts }) {
     const rawSource = readFileSync(fullPath, 'utf8');
     const inlineServerScript = extractServerScript(rawSource, fullPath, compilerOpts).serverScript;

package/dist/preview/create-preview-server.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 function createPreviewServer(options: {
+    distDir: string;
+    port?: number;
+    host?: string;
+    logger?: object | null;
+    config?: object;
+    projectRoot?: string;
+}): Promise<{
+    server: import("http").Server;
+    port: number;
+    close: () => void;
+}>;

package/dist/preview/create-preview-server.js

@@ -0,0 +1,71 @@
+import { createServer } from 'node:http';
+import { resolve } from 'node:path';
+import { normalizeBasePath } from '../base-path.js';
+import { resolveBuildAdapter } from '../adapters/resolve-adapter.js';
+import { isConfigKeyExplicit, isLoadedConfig, loadConfig, validateConfig } from '../config.js';
+import { createTrustedOriginResolver } from '../request-origin.js';
+import { supportsTargetRouteCheck } from '../route-check-support.js';
+import { createSilentLogger } from '../ui/logger.js';
+import { createPreviewRequestHandler } from './request-handler.js';
+/**
+ * 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'
+    });
+    const server = createServer(createPreviewRequestHandler({
+        distDir,
+        projectRoot,
+        config,
+        logger,
+        verboseLogging,
+        configuredBasePath,
+        routeCheckEnabled,
+        isStaticExportTarget,
+        serverOrigin: resolveServerOrigin
+    }));
+    return new Promise((resolveServer) => {
+        server.listen(port, host, () => {
+            actualPort = server.address().port;
+            resolveServer({
+                server,
+                port: actualPort,
+                close: () => {
+                    server.close();
+                }
+            });
+        });
+    });
+}

package/dist/preview/manifest.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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 function loadRouteManifest(distDir: string): Promise<PreviewRoute[]>;
+export function loadRouteSurfaceState(distDir: any, fallbackBasePath?: string): Promise<{
+    basePath: string;
+    pageRoutes: any;
+    resourceRoutes: any[];
+}>;
+export const matchRoute: typeof matchManifestRoute;
+export type PreviewRoute = {
+    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;
+};
+import { matchRoute as matchManifestRoute } from '../server/resolve-request-route.js';

package/dist/preview/manifest.js

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { normalizeBasePath } from '../base-path.js';
+import { loadResourceRouteManifest } from '../resource-manifest.js';
+import { compareRouteSpecificity, matchRoute as matchManifestRoute } from '../server/resolve-request-route.js';
+/**
+ * @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;

package/dist/preview/paths.d.ts

@@ -0,0 +1,3 @@
+export function toStaticFilePath(distDir: any, pathname: any): string | null;
+export function resolveWithinDist(distDir: any, requestPath: any): string | null;
+export function fileExists(fullPath: any): Promise<boolean>;

package/dist/preview/paths.js

@@ -0,0 +1,38 @@
+import { access } from 'node:fs/promises';
+import { extname, normalize, resolve, sep } from 'node:path';
+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;
+}
+export async function fileExists(fullPath) {
+    try {
+        await access(fullPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/preview/payload.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {string} html
+ * @param {Record<string, unknown>} payload
+ * @returns {string}
+ */
+export function injectSsrPayload(html: string, payload: Record<string, unknown>): string;

package/dist/preview/payload.js

@@ -0,0 +1,34 @@
+/**
+ * @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');
+}

package/dist/preview/request-handler.d.ts

@@ -0,0 +1 @@
+export function createPreviewRequestHandler(options: any): (req: any, res: any) => Promise<void>;

package/dist/preview/request-handler.js

@@ -0,0 +1,300 @@
+import { readFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { appLocalRedirectLocation, imageEndpointPath, routeCheckPath, stripBasePath } from '../base-path.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 { buildResourceResponseDescriptor } from '../resource-response.js';
+import { clientFacingRouteMessage, logServerException, sanitizeRouteResult } from '../server-error.js';
+import { resolveRequestRoute } from '../server/resolve-request-route.js';
+import { loadRouteSurfaceState } from './manifest.js';
+import { injectSsrPayload } from './payload.js';
+import { fileExists, resolveWithinDist, toStaticFilePath } from './paths.js';
+import { executeServerRoute, routeIdFromSourcePath } from './server-runner.js';
+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;
+}
+export function createPreviewRequestHandler(options) {
+    const { distDir, projectRoot, config, logger, verboseLogging, configuredBasePath, routeCheckEnabled, isStaticExportTarget, serverOrigin } = options;
+    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 {};
+        }
+    }
+    return async function previewRequestHandler(req, res) {
+        const url = new URL(req.url, serverOrigin());
+        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');
+        }
+    };
+}