@zenithbuild/cli 0.7.10 → 0.7.12

package/dist/manifest.js

@@ -1,26 +1,41 @@
-// ---------------------------------------------------------------------------
-// manifest.js — Zenith CLI V0
-// ---------------------------------------------------------------------------
-// File-based manifest engine.
-//
-// Scans a /pages directory and produces a deterministic RouteManifest.
-//
-// Rules:
-//   - index.zen → parent directory path
-//   - [param].zen → :param dynamic segment
-//   - [...slug].zen → *slug catch-all segment (must be terminal, 1+ segments;
-//                     root '/*slug' may match '/' in router matcher)
-//   - [[...slug]].zen → *slug? optional catch-all segment (must be terminal, 0+ segments)
-//   - Deterministic precedence: static > :param > *catchall
-//   - Tie-breaker: lexicographic route path
-// ---------------------------------------------------------------------------
-import { readFileSync } from 'node:fs';
+// File-based manifest engine. Scans /pages and produces deterministic RouteManifest entries.
+// Rules: static > :param > *catchall, then lexicographic tie-breaker.
+import { readFileSync, existsSync } from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
 import { join, relative, sep, basename, extname, dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { extractServerScript } from './build/server-script.js';
 import { analyzeResourceRouteModule, isResourceRouteFile } from './resource-route-module.js';
 import { composeServerScriptEnvelope, resolveAdjacentServerModules } from './server-script-composition.js';
 import { validateStaticExportPaths } from './static-export-paths.js';
+import { classifyPageRoute } from './route-classification.js';
+import { buildComponentRegistry } from './resolve-components.js';
+const SCOPED_SERVER_DATA_HELPER_UNAVAILABLE = '[Zenith:ScopedServerData] Manifest integration helper is unavailable. Run the CLI build step before using scoped server data manifest integration.';
+function resolveManifestIntegrationPath() {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    return [
+        join(moduleDir, 'scoped-server-data', 'manifest-integration.js'),
+        join(moduleDir, '..', 'dist', 'scoped-server-data', 'manifest-integration.js')
+    ].find((candidate) => existsSync(candidate)) || null;
+}
+const manifestIntegrationPath = resolveManifestIntegrationPath();
+const manifestIntegration = manifestIntegrationPath
+    ? await import(pathToFileURL(manifestIntegrationPath).href)
+    : null;
+function getManifestIntegration() {
+    if (!manifestIntegration) {
+        throw new Error(SCOPED_SERVER_DATA_HELPER_UNAVAILABLE);
+    }
+    return manifestIntegration;
+}
+/** @type {typeof import('./scoped-server-data/manifest-integration.js').analyzeRouteScopedServerMetadata} */
+export function analyzeRouteScopedServerMetadata(options) {
+    return getManifestIntegration().analyzeRouteScopedServerMetadata(options);
+}
+/** @type {typeof import('./scoped-server-data/manifest-integration.js').assertNoScopedServerBuildErrors} */
+export function assertNoScopedServerBuildErrors(diagnostics, contextFile) {
+    return getManifestIntegration().assertNoScopedServerBuildErrors(diagnostics, contextFile);
+}
 /**
  * @typedef {{
  *   path: string,
@@ -34,6 +49,8 @@ import { validateStaticExportPaths } from './static-export-paths.js';
  *   has_guard?: boolean,
  *   has_load?: boolean,
  *   has_action?: boolean,
+ *   has_scoped_server_data?: boolean,
+ *   scoped_server_data?: import('./scoped-server-data/types.js').ManifestScopedServerDataEntry[],
  *   export_paths?: string[]
  * }} ManifestEntry
  */
@@ -42,11 +59,15 @@ import { validateStaticExportPaths } from './static-export-paths.js';
  *
  * @param {string} pagesDir - Absolute path to /pages directory
  * @param {string} [extension='.zen'] - File extension to scan for
- * @param {{ compilerOpts?: object }} [options]
+ * @param {{ compilerOpts?: object, srcDir?: string, registry?: Map<string, string> }} [options]
  * @returns {Promise<ManifestEntry[]>}
  */
 export async function generateManifest(pagesDir, extension = '.zen', options = {}) {
-    const entries = await _scanDir(pagesDir, pagesDir, extension, options.compilerOpts || {});
+    const resolvedPagesDir = resolve(pagesDir);
+    const srcDir = resolve(options.srcDir || resolve(resolvedPagesDir, '..'));
+    const registry = options.registry || buildComponentRegistry(srcDir);
+    const scanContext = { srcDir, registry, compilerOpts: options.compilerOpts || {} };
+    const entries = await _scanDir(resolvedPagesDir, resolvedPagesDir, extension, scanContext);
     const apiAliasState = _resolveSrcApiAliasState(pagesDir);
     if (apiAliasState) {
         const aliasEntries = await _scanResourceDir(apiAliasState.aliasDir, apiAliasState.srcDir);
@@ -68,7 +89,7 @@ export async function generateManifest(pagesDir, extension = '.zen', options = {
  * @param {string} ext - Extension to match
  * @returns {Promise<ManifestEntry[]>}
  */
-async function _scanDir(dir, root, ext, compilerOpts) {
+async function _scanDir(dir, root, ext, scanContext) {
     /** @type {ManifestEntry[]} */
     const entries = [];
     let items;
@@ -84,7 +105,7 @@ async function _scanDir(dir, root, ext, compilerOpts) {
         const fullPath = join(dir, item);
         const info = await stat(fullPath);
         if (info.isDirectory()) {
-            const nested = await _scanDir(fullPath, root, ext, compilerOpts);
+            const nested = await _scanDir(fullPath, root, ext, scanContext);
             entries.push(...nested);
         }
         else if (item.endsWith(ext)) {
@@ -93,7 +114,7 @@ async function _scanDir(dir, root, ext, compilerOpts) {
                 fullPath,
                 root,
                 routePath,
-                compilerOpts
+                scanContext
             }));
         }
         else if (isResourceRouteFile(item)) {
@@ -142,7 +163,8 @@ function _resolveSrcApiAliasState(pagesDir) {
         srcDir
     };
 }
-function buildPageManifestEntry({ fullPath, root, routePath, compilerOpts }) {
+function buildPageManifestEntry({ fullPath, root, routePath, scanContext }) {
+    const { srcDir, registry, compilerOpts } = scanContext;
     const rawSource = readFileSync(fullPath, 'utf8');
     const inlineServerScript = extractServerScript(rawSource, fullPath, compilerOpts).serverScript;
     const { guardPath, loadPath, actionPath } = resolveAdjacentServerModules(fullPath);
@@ -153,16 +175,39 @@ function buildPageManifestEntry({ fullPath, root, routePath, compilerOpts }) {
         adjacentLoadPath: loadPath,
         adjacentActionPath: actionPath
     });
+    const scopedMetadata = analyzeRouteScopedServerMetadata({
+        pageSource: rawSource,
+        pageFile: fullPath,
+        registry,
+        srcDir,
+        compilerOpts
+    });
+    const manifestFile = relative(root, fullPath);
+    assertNoScopedServerBuildErrors(scopedMetadata.diagnostics, manifestFile);
     const exportPaths = Array.isArray(composed.serverScript?.export_paths)
         ? validateStaticExportPaths(routePath, composed.serverScript.export_paths, fullPath)
         : [];
+    const classification = classifyPageRoute({
+        file: manifestFile,
+        serverScript: composed.serverScript,
+        hasScopedServerData: scopedMetadata.hasScopedServerData
+    });
     return {
         path: routePath,
-        file: relative(root, fullPath),
+        file: manifestFile,
         route_kind: 'page',
         path_kind: _isDynamic(routePath) ? 'dynamic' : 'static',
-        render_mode: composed.serverScript && composed.serverScript.prerender !== true ? 'server' : 'prerender',
+        render_mode: classification.renderMode,
         params: extractRouteParams(routePath),
+        has_guard: classification.hasGuard,
+        has_load: classification.hasLoad,
+        has_action: classification.hasAction,
+        ...(scopedMetadata.hasScopedServerData
+            ? {
+                has_scoped_server_data: true,
+                scoped_server_data: scopedMetadata.scopedServerData
+            }
+            : {}),
         ...(exportPaths.length > 0 ? { export_paths: exportPaths } : {})
     };
 }

package/dist/preview/request-handler.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { extname, join } from 'node:path';
+import { dirname, 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';
@@ -8,6 +8,7 @@ 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 { loadPreviewGlobalMiddlewareSource } from '../global-middleware-runtime-source.js';
 import { loadRouteSurfaceState } from './manifest.js';
 import { injectSsrPayload } from './payload.js';
 import { fileExists, resolveWithinDist, toStaticFilePath } from './paths.js';
@@ -32,6 +33,47 @@ function appendSetCookieHeaders(headers, setCookies = []) {
     }
     return headers;
 }
+function respondWithMiddlewareSourceError(res, error) {
+    logServerException('preview server route execution failed', error);
+    res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end(clientFacingRouteMessage(500));
+}
+function hasRouteScopedServerData(route) {
+    return route?.has_scoped_server_data === true &&
+        Array.isArray(route?.scoped_server_data) &&
+        route.scoped_server_data.length > 0;
+}
+async function loadPreviewScopedServerRoutes(serverModuleBaseDir) {
+    try {
+        const parsed = JSON.parse(await readFile(join(serverModuleBaseDir, 'manifest.json'), 'utf8'));
+        return Array.isArray(parsed?.routes) ? parsed.routes : [];
+    }
+    catch {
+        return [];
+    }
+}
+function mergePreviewScopedServerRoutes(routeState, serverRoutes) {
+    const scopedByPath = new Map((Array.isArray(serverRoutes) ? serverRoutes : [])
+        .filter((route) => hasRouteScopedServerData(route))
+        .map((route) => [route.path, route]));
+    if (scopedByPath.size === 0) {
+        return routeState;
+    }
+    return {
+        ...routeState,
+        pageRoutes: (Array.isArray(routeState.pageRoutes) ? routeState.pageRoutes : []).map((route) => {
+            const scoped = scopedByPath.get(route.path);
+            if (!scoped) {
+                return route;
+            }
+            return {
+                ...route,
+                has_scoped_server_data: true,
+                scoped_server_data: scoped.scoped_server_data
+            };
+        })
+    };
+}
 export function createPreviewRequestHandler(options) {
     const { distDir, projectRoot, config, logger, verboseLogging, configuredBasePath, routeCheckEnabled, isStaticExportTarget, serverOrigin } = options;
     async function loadImageManifest() {
@@ -44,9 +86,14 @@ export function createPreviewRequestHandler(options) {
             return {};
         }
     }
+    async function loadGlobalMiddlewareForRoute() {
+        return loadPreviewGlobalMiddlewareSource({ projectRoot, distDir });
+    }
     return async function previewRequestHandler(req, res) {
         const url = new URL(req.url, serverOrigin());
-        const { basePath, pageRoutes, resourceRoutes } = await loadRouteSurfaceState(distDir, configuredBasePath);
+        const serverModuleBaseDir = join(dirname(distDir), 'server');
+        const routeState = mergePreviewScopedServerRoutes(await loadRouteSurfaceState(distDir, configuredBasePath), await loadPreviewScopedServerRoutes(serverModuleBaseDir));
+        const { basePath, pageRoutes, resourceRoutes } = routeState;
         const canonicalPath = stripBasePath(url.pathname, basePath);
         try {
             if (url.pathname === routeCheckPath(basePath)) {
@@ -171,6 +218,14 @@ export function createPreviewRequestHandler(options) {
             canonicalUrl.pathname = canonicalPath;
             const resolvedResource = resolveRequestRoute(canonicalUrl, resourceRoutes);
             if (resolvedResource.matched && resolvedResource.route) {
+                let globalMiddleware = null;
+                try {
+                    globalMiddleware = await loadGlobalMiddlewareForRoute();
+                }
+                catch (error) {
+                    respondWithMiddlewareSourceError(res, error);
+                    return;
+                }
                 const requestMethod = req.method || 'GET';
                 const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
                     ? null
@@ -186,7 +241,9 @@ export function createPreviewRequestHandler(options) {
                     routePattern: resolvedResource.route.path,
                     routeFile: resolvedResource.route.server_script_path || '',
                     routeId: resolvedResource.route.route_id || routeIdFromSourcePath(resolvedResource.route.server_script_path || ''),
-                    routeKind: 'resource'
+                    routeKind: 'resource',
+                    globalMiddlewareSource: globalMiddleware?.source || '',
+                    globalMiddlewareSourcePath: globalMiddleware?.sourcePath || ''
                 });
                 const descriptor = buildResourceResponseDescriptor(execution?.result, basePath, Array.isArray(execution?.setCookies) ? execution.setCookies : []);
                 res.writeHead(descriptor.status, appendSetCookieHeaders(descriptor.headers, descriptor.setCookies));
@@ -216,7 +273,17 @@ export function createPreviewRequestHandler(options) {
             }
             let ssrPayload = null;
             let routeExecution = null;
-            if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
+            if (resolved.matched &&
+                resolved.route?.prerender !== true &&
+                (resolved.route?.server_script || hasRouteScopedServerData(resolved.route))) {
+                let globalMiddleware = null;
+                try {
+                    globalMiddleware = await loadGlobalMiddlewareForRoute();
+                }
+                catch (error) {
+                    respondWithMiddlewareSourceError(res, error);
+                    return;
+                }
                 try {
                     const requestMethod = req.method || 'GET';
                     const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
@@ -232,7 +299,13 @@ export function createPreviewRequestHandler(options) {
                         requestBodyBuffer,
                         routePattern: resolved.route.path,
                         routeFile: resolved.route.server_script_path || '',
-                        routeId: resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '')
+                        routeId: resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || ''),
+                        globalMiddlewareSource: globalMiddleware?.source || '',
+                        globalMiddlewareSourcePath: globalMiddleware?.sourcePath || '',
+                        scopedServerData: Array.isArray(resolved.route.scoped_server_data)
+                            ? resolved.route.scoped_server_data
+                            : [],
+                        scopedServerModuleBaseDir: serverModuleBaseDir
                     });
                 }
                 catch (error) {

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

@@ -1,8 +1,8 @@
 /**
- * @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
+ * @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', globalMiddlewareSource?: string, globalMiddlewareSourcePath?: string, scopedServerData?: unknown[], scopedServerModuleBaseDir?: string, scopedServerModuleSources?: unknown[] }} input
  * @returns {Promise<{ result: { kind: string, [key: string]: unknown }, trace: { guard: string, action: string, load: string }, status?: number, setCookies?: string[] }>}
  */
-export function executeServerRoute({ source, sourcePath, params, requestUrl, requestMethod, requestHeaders, requestBodyBuffer, routePattern, routeFile, routeId, routeKind, guardOnly }: {
+export function executeServerRoute({ source, sourcePath, params, requestUrl, requestMethod, requestHeaders, requestBodyBuffer, routePattern, routeFile, routeId, routeKind, guardOnly, globalMiddlewareSource, globalMiddlewareSourcePath, scopedServerData, scopedServerModuleBaseDir, scopedServerModuleSources }: {
     source: string;
     sourcePath: string;
     params: Record<string, string>;
@@ -14,6 +14,11 @@ export function executeServerRoute({ source, sourcePath, params, requestUrl, req
     routeFile?: string;
     routeId?: string;
     routeKind?: "page" | "resource";
+    globalMiddlewareSource?: string;
+    globalMiddlewareSourcePath?: string;
+    scopedServerData?: unknown[];
+    scopedServerModuleBaseDir?: string;
+    scopedServerModuleSources?: unknown[];
 }): Promise<{
     result: {
         kind: string;

package/dist/preview/server-runner.js

@@ -5,11 +5,12 @@ import { clientFacingRouteMessage, defaultRouteDenyMessage } from '../server-err
 import { SERVER_SCRIPT_RUNNER } from './server-script-runner-template.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
- * @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
+ * @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', globalMiddlewareSource?: string, globalMiddlewareSourcePath?: string, scopedServerData?: unknown[], scopedServerModuleBaseDir?: string, scopedServerModuleSources?: unknown[] }} 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()) {
+export async function executeServerRoute({ source, sourcePath, params, requestUrl, requestMethod, requestHeaders, requestBodyBuffer, routePattern, routeFile, routeId, routeKind = 'page', guardOnly = false, globalMiddlewareSource = '', globalMiddlewareSourcePath = '', scopedServerData = [], scopedServerModuleBaseDir = '', scopedServerModuleSources = [] }) {
+    const hasScopedServerData = Array.isArray(scopedServerData) && scopedServerData.length > 0;
+    if ((!source || !String(source).trim()) && !hasScopedServerData) {
         return {
             result: { kind: 'data', data: {} },
             trace: { guard: 'none', action: 'none', load: 'none' }
@@ -27,7 +28,12 @@ export async function executeServerRoute({ source, sourcePath, params, requestUr
         routeFile: routeFile || sourcePath || '',
         routeId: routeId || routeIdFromSourcePath(sourcePath || ''),
         routeKind,
-        guardOnly
+        guardOnly,
+        globalMiddlewareSource,
+        globalMiddlewareSourcePath,
+        scopedServerData,
+        scopedServerModuleBaseDir,
+        scopedServerModuleSources
     });
     if (payload === null || payload === undefined) {
         return {
@@ -110,7 +116,7 @@ export async function executeServerScript(input) {
     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
+ * @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', globalMiddlewareSource?: string, globalMiddlewareSourcePath?: string, scopedServerData?: unknown[], scopedServerModuleBaseDir?: string, scopedServerModuleSources?: unknown[] }} input
  * @returns {Promise<unknown>}
  */
 function spawnNodeServerRunner(input) {
@@ -130,7 +136,14 @@ function spawnNodeServerRunner(input) {
                 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')
+                ZENITH_SERVER_ROUTE_AUTH_PATH: join(__dirname, '..', 'auth', 'route-auth.js'),
+                ZENITH_SERVER_MATCHED_ROUTE_PIPELINE_PATH: join(__dirname, '..', 'server-runtime', 'matched-route-pipeline.js'),
+                ZENITH_GLOBAL_MIDDLEWARE_SOURCE: input.globalMiddlewareSource || '',
+                ZENITH_GLOBAL_MIDDLEWARE_SOURCE_PATH: input.globalMiddlewareSourcePath || '',
+                ZENITH_SCOPED_SERVER_DATA: JSON.stringify(Array.isArray(input.scopedServerData) ? input.scopedServerData : []),
+                ZENITH_SCOPED_SERVER_MODULE_BASE_DIR: input.scopedServerModuleBaseDir || '',
+                ZENITH_SCOPED_SERVER_MODULE_SOURCES: JSON.stringify(Array.isArray(input.scopedServerModuleSources) ? input.scopedServerModuleSources : []),
+                ZENITH_SCOPED_SERVER_RUNTIME_PATH: join(__dirname, '..', 'scoped-server-data', 'runtime.js')
             },
             stdio: ['pipe', 'pipe', 'pipe']
         });

package/dist/preview/server-script-runner-template.js

@@ -15,11 +15,11 @@ 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';
+const globalMiddlewareSource = process.env.ZENITH_GLOBAL_MIDDLEWARE_SOURCE || '';
+const globalMiddlewareSourcePath = process.env.ZENITH_GLOBAL_MIDDLEWARE_SOURCE_PATH || '';
+const scopedServerData = JSON.parse(process.env.ZENITH_SCOPED_SERVER_DATA || '[]'), scopedServerModuleBaseDir = process.env.ZENITH_SCOPED_SERVER_MODULE_BASE_DIR || '', scopedServerModuleSources = JSON.parse(process.env.ZENITH_SCOPED_SERVER_MODULE_SOURCES || '[]');
 
-if (!source.trim()) {
-  process.stdout.write('null');
-  process.exit(0);
-}
+if (!source.trim() && !(Array.isArray(scopedServerData) && scopedServerData.length > 0)) { process.stdout.write('null'); process.exit(0); }
 
 let cachedTypeScript = undefined;
 async function loadTypeScript() {
@@ -332,6 +332,92 @@ async function linkModule(specifier, parentIdentifier) {
   return loadFileModule(resolvedUrl);
 }
 
+function configuredFrameworkUrl(specifier) {
+  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 || '';
+    return {
+      url: pathToFileURL(configuredPath || defaultPath).href,
+      fallbackUrl: pathToFileURL(defaultPath).href,
+      hasConfiguredPath: Boolean(configuredPath)
+    };
+  }
+  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 || '';
+    return {
+      url: pathToFileURL(configuredPath || defaultPath).href,
+      fallbackUrl: pathToFileURL(defaultPath).href,
+      hasConfiguredPath: Boolean(configuredPath)
+    };
+  }
+  if (specifier === 'zenith:scoped-server-data-runtime') { const defaultPath = path.join(process.cwd(), 'node_modules', '@zenithbuild', 'cli', 'src', 'scoped-server-data', 'runtime.js'); const configuredPath = process.env.ZENITH_SCOPED_SERVER_RUNTIME_PATH || ''; return { url: pathToFileURL(configuredPath || defaultPath).href, fallbackUrl: pathToFileURL(defaultPath).href, hasConfiguredPath: Boolean(configuredPath) }; }
+  return null;
+}
+
+async function linkEntryModule(specifier, referencingModule) {
+  const frameworkUrl = configuredFrameworkUrl(specifier);
+  if (frameworkUrl) {
+    if (frameworkUrl.hasConfiguredPath) {
+      return loadFileModule(frameworkUrl.url);
+    }
+    return loadFileModule(frameworkUrl.url).catch(() =>
+      loadFileModule(frameworkUrl.fallbackUrl)
+    );
+  }
+  return linkModule(specifier, referencingModule.identifier);
+}
+
+async function loadMatchedRoutePipeline() {
+  const defaultPath = path.join(process.cwd(), 'node_modules', '@zenithbuild', 'cli', 'src', 'server-runtime', 'matched-route-pipeline.js');
+  const configuredPath = process.env.ZENITH_SERVER_MATCHED_ROUTE_PIPELINE_PATH || '';
+  const pipelineUrl = pathToFileURL(configuredPath || defaultPath).href;
+  const module = await loadFileModule(pipelineUrl).catch((error) => {
+    if (configuredPath) {
+      throw error;
+    }
+    return loadFileModule(pathToFileURL(defaultPath).href);
+  });
+  await module.evaluate();
+  if (typeof module.namespace.executeMatchedRoutePipeline !== 'function') {
+    throw new Error('[zenith-preview] matched route pipeline unavailable');
+  }
+  return module.namespace.executeMatchedRoutePipeline;
+}
+
+async function loadGlobalMiddleware() {
+  if (!globalMiddlewareSource.trim()) {
+    return null;
+  }
+  const identifier = globalMiddlewareSourcePath
+    ? pathToFileURL(globalMiddlewareSourcePath).href
+    : 'zenith:global-middleware';
+  const filename = globalMiddlewareSourcePath || 'global-middleware.ts';
+  const code = await transpileIfNeeded(filename, globalMiddlewareSource);
+  const module = new vm.SourceTextModule(code, {
+    context,
+    identifier,
+    initializeImportMeta(meta) {
+      meta.url = identifier;
+    }
+  });
+  moduleCache.set(identifier, module);
+  await module.link(linkEntryModule);
+  await module.evaluate();
+  const middlewareFn = module.namespace.default;
+  if (typeof middlewareFn !== 'function') {
+    throw new Error('[Zenith:Middleware] Global middleware module must default export a function.');
+  }
+  return middlewareFn;
+}
+
+async function loadScopedServerRuntime() { const module = await linkEntryModule('zenith:scoped-server-data-runtime', null); await module.evaluate(); if (typeof module.namespace.executeScopedServerData !== 'function' || typeof module.namespace.mergeScopedSsrPayload !== 'function') throw new Error('[zenith-preview] scoped server data runtime unavailable'); return module.namespace; }
+async function loadScopedSourceModule(entry) { const modulePath = String(entry && entry.module || ''); const found = Array.isArray(scopedServerModuleSources) ? scopedServerModuleSources.find((item) => item && item.module === modulePath) : null; if (!found || typeof found.source !== 'string') throw new Error('[Zenith:ScopedServerData] Missing scoped server data source for "' + modulePath + '".'); const sourcePath = typeof found.sourcePath === 'string' && found.sourcePath.length > 0 ? found.sourcePath : modulePath; const identifier = sourcePath.startsWith('file:') ? sourcePath : pathToFileURL(sourcePath).href; const filename = sourcePath.toLowerCase().endsWith('.zen') ? sourcePath.replace(/\.zen$/i, '.ts') : sourcePath; const code = await transpileIfNeeded(filename, found.source); const module = new vm.SourceTextModule(code, { context, identifier, initializeImportMeta(meta) { meta.url = identifier; } }); moduleCache.set(identifier, module); await module.link(linkEntryModule); await module.evaluate(); return module.namespace; }
+function invalidScopedModulePath() { throw new Error('[Zenith:ScopedServerData] Invalid scoped server data module path.'); }
+function resolveScopedPackagedModulePath(entry) { const modulePath = String(entry && entry.module || ''); if (!modulePath || path.isAbsolute(modulePath) || /^[A-Za-z]:[\\/]/.test(modulePath)) invalidScopedModulePath(); const normalized = modulePath.replace(/\\/g, '/'); if (!normalized.startsWith('scoped/') || normalized.split('/').some((part) => part === '..' || part === '.')) invalidScopedModulePath(); const scopedRoot = path.resolve(scopedServerModuleBaseDir, 'scoped'); const candidate = path.resolve(scopedServerModuleBaseDir, normalized); if (candidate !== scopedRoot && !candidate.startsWith(scopedRoot + path.sep)) invalidScopedModulePath(); return candidate; }
+async function loadScopedPackagedModule(entry) { if (!scopedServerModuleBaseDir) throw new Error('[Zenith:ScopedServerData] Cannot execute scoped server data without a server module root.'); const module = await loadFileModule(pathToFileURL(resolveScopedPackagedModulePath(entry)).href); await module.evaluate(); return module.namespace; }
+async function executeScopedServerDataAfterRoute(resolved) { if (guardOnly || routeKind === 'resource' || !Array.isArray(scopedServerData) || scopedServerData.length === 0 || !resolved || !resolved.result || resolved.result.kind !== 'data') return resolved; const runtime = await loadScopedServerRuntime(); const scoped = await runtime.executeScopedServerData({ route: { route_kind: routeKind, prerender: false, has_scoped_server_data: true, scoped_server_data: scopedServerData }, ctx: context.ctx, loadModule: (entry) => Array.isArray(scopedServerModuleSources) && scopedServerModuleSources.length > 0 ? loadScopedSourceModule(entry) : loadScopedPackagedModule(entry) }); return { ...resolved, result: { ...resolved.result, data: runtime.mergeScopedSsrPayload(resolved.result.data, scoped) } }; }
+
 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" +
@@ -358,29 +444,7 @@ const entryModule = new vm.SourceTextModule(entryCode, {
 
 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);
+  return linkEntryModule(specifier, referencingModule);
 });
 await entryModule.evaluate();
 context.attachRouteAuth(routeContext, {
@@ -399,13 +463,17 @@ for (const key of namespaceKeys) {
 
 const exported = entryModule.namespace;
 try {
-  const resolved = await context.resolveRouteResult({
+  const executeMatchedRoutePipeline = await loadMatchedRoutePipeline();
+  const globalMiddleware = await loadGlobalMiddleware();
+  let resolved = await executeMatchedRoutePipeline({
     exports: exported,
     ctx: context.ctx,
     filePath: sourcePath || 'server_script',
     guardOnly: guardOnly,
-    routeKind: routeKind
+    routeKind: routeKind,
+    globalMiddleware
   });
+  resolved = await executeScopedServerDataAfterRoute(resolved);
 
   process.stdout.write(JSON.stringify(resolved || null));
 } catch (error) {

package/dist/resource-response.js

@@ -28,6 +28,24 @@ function createReadableStreamFromAsyncIterable(iterable) {
         }
     });
 }
+const SSE_METADATA_CONTROL_RE = /[\x00-\x1F\x7F]/u;
+function serializeSseMetadata(value, field) {
+    const serialized = String(value);
+    if (SSE_METADATA_CONTROL_RE.test(serialized)) {
+        throw new Error(`[Zenith] sse ${field} metadata must be a single line without control characters.`);
+    }
+    return serialized;
+}
+function serializeSseRetry(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error('[Zenith] sse retry metadata must be a non-negative safe integer.');
+    }
+    return String(value);
+}
+function serializeSseData(value) {
+    const raw = typeof value === 'string' ? value : JSON.stringify(value);
+    return String(raw ?? '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
 function createSseStream(events) {
     const iterator = events[Symbol.asyncIterator]();
     const encoder = new TextEncoder();
@@ -40,14 +58,13 @@ function createSseStream(events) {
                     return;
                 }
                 let chunk = '';
-                if (value.event)
-                    chunk += `event: ${value.event}\n`;
-                if (value.id)
-                    chunk += `id: ${value.id}\n`;
-                if (value.retry)
-                    chunk += `retry: ${value.retry}\n`;
-                const data = typeof value.data === 'string' ? value.data : JSON.stringify(value.data);
-                const lines = data.split('\n');
+                if (value.event !== undefined)
+                    chunk += `event: ${serializeSseMetadata(value.event, 'event')}\n`;
+                if (value.id !== undefined)
+                    chunk += `id: ${serializeSseMetadata(value.id, 'id')}\n`;
+                if (value.retry !== undefined)
+                    chunk += `retry: ${serializeSseRetry(value.retry)}\n`;
+                const lines = serializeSseData(value.data).split('\n');
                 for (const line of lines) {
                     chunk += `data: ${line}\n`;
                 }

package/dist/resource-route-module.js

@@ -1,27 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { relative, sep } from 'node:path';
+import { readRouteHandlerExport } from './route-handler-export-analysis.js';
 const RESOURCE_EXTENSIONS = ['.resource.ts', '.resource.js', '.resource.mts', '.resource.cts', '.resource.mjs', '.resource.cjs'];
 const FORBIDDEN_RESOURCE_EXPORT_RE = /\bexport\s+const\s+(?:data|prerender|exportPaths|ssr_data|props|ssr)\b/;
-function readSingleExport(source, name) {
-    const fnMatch = source.match(new RegExp(`\\bexport\\s+(?:async\\s+)?function\\s+${name}\\s*\\(([^)]*)\\)`));
-    const constParenMatch = source.match(new RegExp(`\\bexport\\s+const\\s+${name}\\s*=\\s*(?:async\\s*)?\\(([^)]*)\\)\\s*=>`));
-    const constSingleArgMatch = source.match(new RegExp(`\\bexport\\s+const\\s+${name}\\s*=\\s*(?:async\\s*)?([a-zA-Z_$][a-zA-Z0-9_$]*)\\s*=>`));
-    const matchCount = Number(Boolean(fnMatch)) +
-        Number(Boolean(constParenMatch)) +
-        Number(Boolean(constSingleArgMatch));
-    return {
-        fnMatch,
-        constParenMatch,
-        constSingleArgMatch,
-        hasExport: matchCount > 0,
-        matchCount
-    };
-}
 function assertSingleCtxArg(sourceFile, name, exportMatch) {
-    const singleArg = String(exportMatch.constSingleArgMatch?.[1] || '').trim();
-    const paramsText = String((exportMatch.fnMatch || exportMatch.constParenMatch)?.[1] || '').trim();
-    const arity = singleArg ? 1 : paramsText.length === 0 ? 0 : paramsText.split(',').length;
-    if (arity !== 1) {
+    if (exportMatch.arity !== null && exportMatch.arity !== 1) {
         throw new Error(`Zenith resource route contract violation:\n` +
             `  File: ${sourceFile}\n` +
             `  Reason: ${name}(ctx) must accept exactly one argument\n` +
@@ -80,9 +63,9 @@ export function analyzeResourceRouteModule(fullPath, root) {
             `  Reason: resource routes may only export guard(ctx), load(ctx), and action(ctx)\n` +
             `  Example: remove page-only exports such as data/prerender/exportPaths`);
     }
-    const guardExport = readSingleExport(source, 'guard');
-    const loadExport = readSingleExport(source, 'load');
-    const actionExport = readSingleExport(source, 'action');
+    const guardExport = readRouteHandlerExport(source, 'guard');
+    const loadExport = readRouteHandlerExport(source, 'load');
+    const actionExport = readRouteHandlerExport(source, 'action');
     for (const [name, exportMatch] of [
         ['guard', guardExport],
         ['load', loadExport],

package/dist/route-classification.d.ts

@@ -0,0 +1,11 @@
+export function classifyPageRoute({ file, serverScript, hasScopedServerData }: {
+    file: any;
+    serverScript: any;
+    hasScopedServerData?: boolean | undefined;
+}): {
+    prerender: boolean;
+    renderMode: string;
+    hasGuard: boolean;
+    hasLoad: boolean;
+    hasAction: boolean;
+};