@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

package/src/adapters/shared/http/fs-server-response-factory.js

@@ -0,0 +1,106 @@
+import { STATUS_MESSAGE } from '../../../config/constants.js';
+import { appLogger } from '../../../global/app-logger.js';
+import { fileSystem } from '@ecopages/file-system';
+/**
+ * Builds HTTP responses for static files and shared file-system fallbacks.
+ */
+export class FileSystemServerResponseFactory {
+    options;
+    constructor({ options }) {
+        this.options = options;
+    }
+    isHtml(contentType) {
+        return contentType === 'text/html';
+    }
+    shouldEnableGzip(contentType) {
+        if (this.options.watchMode)
+            return false;
+        const gzipEnabledExtensions = ['text/javascript', 'text/css'];
+        return gzipEnabledExtensions.includes(contentType);
+    }
+    async createResponseWithBody(body, init = {
+        headers: {
+            'Content-Type': 'text/html',
+        },
+    }) {
+        return new Response(body, init);
+    }
+    async createDefaultNotFoundResponse() {
+        return new Response(STATUS_MESSAGE[404], {
+            status: 404,
+        });
+    }
+    /**
+     * Wraps already-rendered HTML in a 404 response envelope.
+     */
+    async createHtmlNotFoundResponse(body) {
+        return await this.createResponseWithBody(body, {
+            status: 404,
+            statusText: STATUS_MESSAGE[404],
+            headers: {
+                'Content-Type': 'text/html',
+            },
+        });
+    }
+    async createDefaultServerErrorResponse() {
+        return new Response(STATUS_MESSAGE[500], {
+            status: 500,
+            headers: {
+                'Content-Type': 'text/plain; charset=utf-8',
+            },
+        });
+    }
+    /**
+     * Wraps already-rendered HTML in a 500 response envelope.
+     */
+    async createHtmlServerErrorResponse(body) {
+        return await this.createResponseWithBody(body, {
+            status: 500,
+            statusText: STATUS_MESSAGE[500],
+            headers: {
+                'Content-Type': 'text/html',
+            },
+        });
+    }
+    /**
+     * Reads a static file response, returning `null` when the file is missing.
+     */
+    async createFileResponse(filePath, contentType) {
+        try {
+            let file;
+            const contentEncodingHeader = {};
+            if (this.shouldEnableGzip(contentType)) {
+                const gzipPath = `${filePath}.gz`;
+                if (fileSystem.exists(gzipPath)) {
+                    file = fileSystem.readFileAsBuffer(gzipPath);
+                    contentEncodingHeader['Content-Encoding'] = 'gzip';
+                    contentEncodingHeader['Vary'] = 'Accept-Encoding';
+                }
+                else {
+                    appLogger.debug('Gzip file not found, serving uncompressed', gzipPath);
+                    file = fileSystem.readFileAsBuffer(filePath);
+                }
+            }
+            else {
+                file = fileSystem.readFileAsBuffer(filePath);
+            }
+            return await this.createResponseWithBody(file, {
+                headers: {
+                    'Content-Type': contentType,
+                    ...contentEncodingHeader,
+                },
+            });
+        }
+        catch (error) {
+            const err = error;
+            const code = err.code || err.cause?.code;
+            if (code === 'ENOENT') {
+                appLogger.debug('File not found', filePath);
+            }
+            else {
+                appLogger.error('Error reading file', filePath, err);
+            }
+            return null;
+        }
+    }
+}

package/src/adapters/shared/{fs-server-response-matcher.d.ts → http/fs-server-response-matcher.d.ts}

@@ -1,8 +1,8 @@
-import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.js';
-import type { PageRendererResolver } from '../../route-renderer/route-renderer.js';
-import type { RouteRegistry } from '../../router/server/route-registry.js';
-import type { PageCacheService } from '../../services/cache/page-cache-service.js';
-import type { CacheStrategy } from '../../services/cache/cache.types.js';
+import type { EcoPagesAppConfig, MatchResult } from '../../../types/internal-types.js';
+import type { PageRendererResolver } from '../../../route-renderer/route-renderer.js';
+import type { RouteRegistry } from '../../../router/server/route-registry.js';
+import type { PageCacheService } from '../../../services/cache/page-cache-service.js';
+import type { CacheStrategy } from '../../../services/cache/cache.types.js';
 import type { FileSystemServerResponseFactory } from './fs-server-response-factory.js';
 export interface FileSystemResponseMatcherOptions {
     appConfig: EcoPagesAppConfig;
@@ -55,6 +55,26 @@ export declare class FileSystemResponseMatcher {
      * when the page template cannot be resolved.
      */
     private renderCustomNotFoundResponse;
+    /**
+     * Renders the app-owned custom 500 page, falling back to the default text 500
+     * when the page template cannot be resolved.
+     */
+    private renderCustomServerErrorResponse;
+    /**
+     * Builds development-only error details for the custom 500 page.
+     * @remarks Production omits these fields so stacks are not serialized into HTML.
+     */
+    private buildServerErrorPageProps;
+    private renderCustomErrorPageResponse;
+    private renderCustomNotFoundResponseOrServerError;
+    /**
+     * Logs the original render failure, then tries the custom 500 page once.
+     * @remarks Any failure while rendering the custom 500 page falls back to the
+     * default plain-text response and never re-enters the custom page path.
+     * In development the thrown error's `message` and `stack` are passed into the
+     * custom 500 page props.
+     */
+    private createInternalServerErrorResponse;
     private createExecutionPlan;
     /**
      * Loads the matched page module for request-time inspection.

package/src/adapters/shared/http/fs-server-response-matcher.js

@@ -0,0 +1,258 @@
+import path from 'node:path';
+import { appLogger } from '../../../global/app-logger.js';
+import { PageRequestCacheCoordinator } from '../../../services/cache/page-request-cache-coordinator.service.js';
+import { ServerUtils } from '../../../utils/server-utils.module.js';
+import { FileRouteMiddlewarePipeline } from './file-route-middleware-pipeline.js';
+import { HttpError } from '../../../errors/http-error.js';
+import { LocalsAccessError } from '../../../errors/locals-access-error.js';
+import { isDevelopmentRuntime } from '../../../utils/runtime.js';
+/**
+ * Matches file-system routes to rendered HTML responses.
+ *
+ * This render pipeline coordinates page module inspection, request-local policy,
+ * renderer invocation, middleware execution, cache integration, and fallback
+ * error translation.
+ */
+export class FileSystemResponseMatcher {
+    appConfig;
+    assetPrefix;
+    router;
+    routeRendererFactory;
+    fileSystemResponseFactory;
+    pageRequestCacheCoordinator;
+    fileRouteMiddlewarePipeline;
+    constructor({ appConfig, assetPrefix, router, routeRendererFactory, fileSystemResponseFactory, cacheService = null, defaultCacheStrategy = 'static', }) {
+        this.appConfig = appConfig;
+        this.assetPrefix = assetPrefix;
+        this.router = router;
+        this.routeRendererFactory = routeRendererFactory;
+        this.fileSystemResponseFactory = fileSystemResponseFactory;
+        this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy);
+        this.fileRouteMiddlewarePipeline = new FileRouteMiddlewarePipeline(cacheService);
+    }
+    /**
+     * Resolves unmatched paths either as static asset requests or as the custom
+     * not-found page.
+     * @param requestUrl Incoming pathname.
+     * @returns Static file response or rendered 404 response.
+     */
+    async handleNoMatch(requestUrl) {
+        const isStaticFileRequest = ServerUtils.hasKnownStaticExtension(requestUrl);
+        if (!isStaticFileRequest) {
+            return this.renderCustomNotFoundResponseOrServerError(requestUrl);
+        }
+        const relativeUrl = requestUrl.startsWith('/') ? requestUrl.slice(1) : requestUrl;
+        const filePath = path.join(this.assetPrefix, relativeUrl);
+        const contentType = ServerUtils.getContentType(filePath);
+        const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+        return response ?? this.renderCustomNotFoundResponseOrServerError(requestUrl);
+    }
+    /**
+     * Handles a matched file-system page route.
+     *
+     * The method inspects page metadata needed for request-time execution,
+     * prepares the renderer invocation, validates middleware/cache constraints,
+     * and delegates caching plus middleware execution to dedicated collaborators.
+     *
+     * @param match Router match result.
+     * @param request Optional incoming request. A synthetic GET request is created when omitted.
+     * @returns Final response for the matched route.
+     */
+    async handleMatch(match, request) {
+        try {
+            const executionPlan = await this.createExecutionPlan(match, request);
+            this.fileRouteMiddlewarePipeline.assertValidConfiguration({
+                middleware: executionPlan.pageMiddleware,
+                pageCacheStrategy: executionPlan.pageCacheStrategy,
+                filePath: executionPlan.pageFilePath,
+            });
+            const routeRenderer = this.routeRendererFactory.getPageRenderer(executionPlan.pageFilePath);
+            const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
+                request: executionPlan.request,
+                params: match.params,
+                locals: executionPlan.localsStore,
+            });
+            const renderFn = async () => {
+                const result = await routeRenderer.execute({
+                    file: executionPlan.pageFilePath,
+                    pageModule: executionPlan.pageModule,
+                    params: match.params,
+                    query: match.query,
+                    locals: executionPlan.localsForRender,
+                });
+                const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
+                const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+                return {
+                    html,
+                    strategy,
+                    sourceDependencyPaths: result.sourceDependencyPaths,
+                };
+            };
+            const renderResponse = async () => {
+                return this.pageRequestCacheCoordinator.render({
+                    cacheKey: executionPlan.cacheKey,
+                    pageCacheStrategy: executionPlan.pageCacheStrategy,
+                    renderFn,
+                });
+            };
+            return await this.fileRouteMiddlewarePipeline.run({
+                middleware: executionPlan.pageMiddleware,
+                context: middlewareContext,
+                renderResponse,
+            });
+        }
+        catch (error) {
+            if (error instanceof Response) {
+                return error;
+            }
+            if (HttpError.isHttpError(error) && error.status === 404) {
+                return await this.renderCustomNotFoundResponseOrServerError(match.requestedPathname);
+            }
+            if (error instanceof LocalsAccessError) {
+                return await this.createInternalServerErrorResponse(error.message, match.requestedPathname, error);
+            }
+            return await this.createInternalServerErrorResponse(error instanceof Error ? error.message : 'Internal Server Error', match.requestedPathname, error);
+        }
+    }
+    /**
+     * Renders the app-owned custom 404 page, falling back to the default text 404
+     * when the page template cannot be resolved.
+     */
+    async renderCustomNotFoundResponse() {
+        return this.renderCustomErrorPageResponse({
+            templatePath: this.appConfig.absolutePaths.error404TemplatePath,
+            label: '404',
+            createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultNotFoundResponse(),
+            createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlNotFoundResponse(body),
+        });
+    }
+    /**
+     * Renders the app-owned custom 500 page, falling back to the default text 500
+     * when the page template cannot be resolved.
+     */
+    async renderCustomServerErrorResponse(error) {
+        return this.renderCustomErrorPageResponse({
+            templatePath: this.appConfig.absolutePaths.error500TemplatePath,
+            label: '500',
+            props: this.buildServerErrorPageProps(error),
+            createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultServerErrorResponse(),
+            createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlServerErrorResponse(body),
+        });
+    }
+    /**
+     * Builds development-only error details for the custom 500 page.
+     * @remarks Production omits these fields so stacks are not serialized into HTML.
+     */
+    buildServerErrorPageProps(error) {
+        if (!isDevelopmentRuntime()) {
+            return undefined;
+        }
+        if (error instanceof Error) {
+            return {
+                message: error.message,
+                stack: error.stack,
+            };
+        }
+        return {
+            message: String(error),
+        };
+    }
+    async renderCustomErrorPageResponse({ templatePath, label, props, createDefaultResponse, createHtmlResponse, }) {
+        let routeRenderer;
+        try {
+            routeRenderer = this.routeRendererFactory.getPageRenderer(templatePath);
+        }
+        catch {
+            appLogger.debug(`Custom ${label} template not found, falling back to default ${label} response`, templatePath);
+            return createDefaultResponse();
+        }
+        const result = await routeRenderer.execute({
+            file: templatePath,
+            props,
+        });
+        return createHtmlResponse(result.body);
+    }
+    async renderCustomNotFoundResponseOrServerError(pathname) {
+        try {
+            return await this.renderCustomNotFoundResponse();
+        }
+        catch (error) {
+            if (error instanceof Response) {
+                return error;
+            }
+            return await this.createInternalServerErrorResponse(error instanceof Error ? error.message : 'Internal Server Error', pathname, error);
+        }
+    }
+    /**
+     * Logs the original render failure, then tries the custom 500 page once.
+     * @remarks Any failure while rendering the custom 500 page falls back to the
+     * default plain-text response and never re-enters the custom page path.
+     * In development the thrown error's `message` and `stack` are passed into the
+     * custom 500 page props.
+     */
+    async createInternalServerErrorResponse(message, pathname, error) {
+        if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
+            appLogger.error(`[FileSystemResponseMatcher] ${message} at ${pathname}`, error);
+        }
+        else {
+            appLogger.error(`[FileSystemResponseMatcher] Render error at ${pathname}`, error);
+        }
+        try {
+            return await this.renderCustomServerErrorResponse(error);
+        }
+        catch (serverErrorPageError) {
+            if (serverErrorPageError instanceof Response) {
+                return serverErrorPageError;
+            }
+            appLogger.error(`[FileSystemResponseMatcher] Custom 500 template failed at ${pathname}`, serverErrorPageError);
+            return this.fileSystemResponseFactory.createDefaultServerErrorResponse();
+        }
+    }
+    async createExecutionPlan(match, request) {
+        const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey({
+            pathname: match.requestedPathname,
+            query: match.query,
+        });
+        const resolvedRequest = request ??
+            new Request(new URL(cacheKey, this.router.origin).toString(), {
+                method: 'GET',
+            });
+        const localsStore = {};
+        const pageFilePath = match.templateRoute.filePath;
+        const pageModule = await this.importPageModule(pageFilePath);
+        const pageComponent = pageModule.default;
+        const pageMiddleware = pageComponent.middleware ?? [];
+        const pageCacheStrategy = pageModule.cache ?? pageComponent.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+        return {
+            cacheKey,
+            request: resolvedRequest,
+            pageFilePath,
+            pageModule,
+            pageMiddleware,
+            pageCacheStrategy,
+            localsStore,
+            localsForRender: pageCacheStrategy === 'dynamic' ? localsStore : undefined,
+        };
+    }
+    /**
+     * Loads the matched page module for request-time inspection.
+     *
+     * The matcher needs access to page-level metadata such as `cache` and
+     * `middleware` before full rendering starts, so it asks the owning route
+     * renderer to load the page module. That preserves integration-specific page
+     * import setup for request-time inspection as well as for full rendering.
+     *
+     * @param filePath Absolute page module path.
+     * @returns Imported page module.
+     */
+    async importPageModule(filePath) {
+        const routeRenderer = this.routeRendererFactory.getPageRenderer(filePath);
+        return routeRenderer.loadPageModule(filePath);
+    }
+    /**
+     * Get the underlying cache service for external invalidation.
+     */
+    getCacheService() {
+        return this.pageRequestCacheCoordinator.getCacheService();
+    }
+}

package/src/adapters/shared/http/run-middleware-chain.d.ts

@@ -0,0 +1,5 @@
+export type MiddlewareHandler<TContext> = (context: TContext, next: () => Promise<Response>) => Response | Promise<Response>;
+/**
+ * Runs an onion middleware chain and invokes the terminal handler when the chain completes.
+ */
+export declare function runMiddlewareChain<TContext>(middleware: readonly MiddlewareHandler<TContext>[], context: TContext, terminal: () => Promise<Response>): Promise<Response>;

package/src/adapters/shared/http/run-middleware-chain.js

@@ -0,0 +1,17 @@
+/**
+ * Runs an onion middleware chain and invokes the terminal handler when the chain completes.
+ */
+export async function runMiddlewareChain(middleware, context, terminal) {
+    if (middleware.length === 0) {
+        return terminal();
+    }
+    let index = 0;
+    const executeNext = async () => {
+        if (index < middleware.length) {
+            const current = middleware[index++];
+            return await current(context, executeNext);
+        }
+        return terminal();
+    };
+    return executeNext();
+}

package/src/adapters/shared/{application-adapter.d.ts → runtime/application-adapter.d.ts}

@@ -1,5 +1,5 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../types/public-types.js';
-import { AbstractApplicationAdapter, type ApplicationAdapterOptions, type RouteGroupDefinition, type RouteHandler } from '../abstract/application-adapter.js';
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../../types/public-types.js';
+import { AbstractApplicationAdapter, type ApplicationAdapterOptions, type RouteGroupDefinition, type RouteHandler } from '../../abstract/application-adapter.js';
 export declare abstract class SharedApplicationAdapter<TOptions extends ApplicationAdapterOptions = ApplicationAdapterOptions, TServer = any, TRequest extends Request = Request> extends AbstractApplicationAdapter<TOptions, TServer, TRequest> {
     protected register<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, method: ApiHandler['method'], handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
     get<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;

package/src/adapters/shared/runtime/application-adapter.js

@@ -0,0 +1,75 @@
+import { AbstractApplicationAdapter, } from '../../abstract/application-adapter.js';
+export class SharedApplicationAdapter extends AbstractApplicationAdapter {
+    register(path, method, handler, options) {
+        return this.addRouteHandler(path, method, handler, options?.middleware, options?.schema);
+    }
+    get(path, handler, options) {
+        return this.register(path, 'GET', handler, options);
+    }
+    post(path, handler, options) {
+        return this.register(path, 'POST', handler, options);
+    }
+    put(path, handler, options) {
+        return this.register(path, 'PUT', handler, options);
+    }
+    delete(path, handler, options) {
+        return this.register(path, 'DELETE', handler, options);
+    }
+    patch(path, handler, options) {
+        return this.register(path, 'PATCH', handler, options);
+    }
+    options(path, handler, options) {
+        return this.register(path, 'OPTIONS', handler, options);
+    }
+    head(path, handler, options) {
+        return this.register(path, 'HEAD', handler, options);
+    }
+    route(path, method, handler, options) {
+        return this.register(path, method, handler, options);
+    }
+    add(handler) {
+        return this.addRouteHandler(handler.path, handler.method, handler.handler, handler.middleware, handler.schema);
+    }
+    group(prefixOrGroup, callback, options) {
+        if (typeof prefixOrGroup === 'object') {
+            return this.registerGroup(prefixOrGroup);
+        }
+        const normalizedPrefix = prefixOrGroup.endsWith('/') ? prefixOrGroup.slice(0, -1) : prefixOrGroup;
+        const groupMiddleware = (options?.middleware ?? []);
+        const createHandler = (method) => {
+            return ((path, handler, routeOptions) => {
+                const combinedMiddleware = [
+                    ...groupMiddleware,
+                    ...(routeOptions?.middleware ?? []),
+                ];
+                const fullPath = path === '/' ? normalizedPrefix : `${normalizedPrefix}${path}`;
+                this.addRouteHandler(fullPath, method, handler, combinedMiddleware.length > 0
+                    ? combinedMiddleware
+                    : undefined, routeOptions?.schema);
+                return builder;
+            });
+        };
+        const builder = {
+            get: createHandler('GET'),
+            post: createHandler('POST'),
+            put: createHandler('PUT'),
+            delete: createHandler('DELETE'),
+            patch: createHandler('PATCH'),
+            options: createHandler('OPTIONS'),
+            head: createHandler('HEAD'),
+        };
+        callback?.(builder);
+        return this;
+    }
+    registerGroup(group) {
+        const normalizedPrefix = group.prefix.endsWith('/') ? group.prefix.slice(0, -1) : group.prefix;
+        const groupMiddleware = group.middleware ?? [];
+        for (const route of group.routes) {
+            const normalizedPath = route.path.startsWith('/') ? route.path : `/${route.path}`;
+            const fullPath = route.path === '/' ? normalizedPrefix : `${normalizedPrefix}${normalizedPath}`;
+            const combinedMiddleware = [...groupMiddleware, ...(route.middleware ?? [])];
+            this.addRouteHandler(fullPath, route.method, route.handler, combinedMiddleware.length > 0 ? combinedMiddleware : undefined, route.schema);
+        }
+        return this;
+    }
+}

package/src/adapters/shared/runtime/collect-dev-prewarm-plan.d.ts

@@ -0,0 +1,11 @@
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { DevPrewarmReadiness } from './dev-static-route-prewarm.js';
+export type DevPrewarmPlan = {
+    pathnames: readonly string[];
+    beforeReadyPathnames: readonly string[];
+    readiness: DevPrewarmReadiness;
+};
+/**
+ * Aggregates processor-declared dev prewarm pathnames and readiness into one plan.
+ */
+export declare function collectAppDevPrewarmPlan(appConfig: EcoPagesAppConfig): Promise<DevPrewarmPlan>;

package/src/adapters/shared/runtime/collect-dev-prewarm-plan.js

@@ -0,0 +1,29 @@
+/**
+ * Aggregates processor-declared dev prewarm pathnames and readiness into one plan.
+ */
+export async function collectAppDevPrewarmPlan(appConfig) {
+    const pathnames = new Set(appConfig.devPrewarmPaths ?? []);
+    const beforeReadyPathnames = new Set(appConfig.devPrewarmBeforeReadyPaths ?? []);
+    let readiness = 'background';
+    for (const processor of appConfig.processors.values()) {
+        const contributor = processor;
+        const plan = await contributor.collectDevPrewarmPlan();
+        for (const pathname of plan.pathnames) {
+            pathnames.add(pathname);
+        }
+        if (plan.readiness === 'beforeReady') {
+            readiness = 'beforeReady';
+            for (const pathname of plan.pathnames) {
+                beforeReadyPathnames.add(pathname);
+            }
+        }
+    }
+    for (const pathname of beforeReadyPathnames) {
+        pathnames.add(pathname);
+    }
+    return {
+        pathnames: [...pathnames],
+        beforeReadyPathnames: [...beforeReadyPathnames],
+        readiness,
+    };
+}

package/src/adapters/shared/runtime/copy-runtime-public-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copies a source public directory into the runtime dist dir, skipping unchanged files.
+ *
+ * Dev restarts call this on every boot; byte comparison avoids rewriting identical assets.
+ */
+export declare function copyRuntimePublicDirIfChanged(sourceDir: string, destinationDir: string): void;

package/src/adapters/shared/runtime/copy-runtime-public-dir.js

@@ -0,0 +1,27 @@
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+/**
+ * Copies a source public directory into the runtime dist dir, skipping unchanged files.
+ *
+ * Dev restarts call this on every boot; byte comparison avoids rewriting identical assets.
+ */
+export function copyRuntimePublicDirIfChanged(sourceDir, destinationDir) {
+    fileSystem.ensureDir(destinationDir);
+    for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationPath = path.join(destinationDir, entry.name);
+        if (entry.isDirectory()) {
+            copyRuntimePublicDirIfChanged(sourcePath, destinationPath);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        if (fileSystem.exists(destinationPath) &&
+            Buffer.compare(fileSystem.readFileAsBuffer(sourcePath), fileSystem.readFileAsBuffer(destinationPath)) === 0) {
+            continue;
+        }
+        fileSystem.copyFile(sourcePath, destinationPath);
+    }
+}

package/src/adapters/shared/runtime/dev-static-route-prewarm.d.ts

@@ -0,0 +1,16 @@
+export type DevPrewarmReadiness = 'background' | 'beforeReady';
+export type DevStaticRoutePrewarmOptions = {
+    pathnames: readonly string[];
+    readiness?: DevPrewarmReadiness;
+    renderPath: (pathname: string) => Promise<void>;
+    /** Invoked with the pathname list before rendering begins. */
+    onPathnamesResolved?: (pathnames: readonly string[]) => void;
+};
+/**
+ * Renders declared pathnames so first client navigations hit warm graphs and scoped watch HTML cache.
+ */
+export declare function runDevStaticRoutePrewarm(options: DevStaticRoutePrewarmOptions): Promise<void>;
+/**
+ * Fire-and-forget wrapper around {@link runDevStaticRoutePrewarm}.
+ */
+export declare function startDevStaticRoutePrewarm(options: DevStaticRoutePrewarmOptions): void;