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

package/src/adapters/shared/runtime/runtime-server-lifecycle.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { RESOLVED_ASSETS_DIR } from '../../../config/constants.js';
+import { disposeAppBuildRuntime } from '../../../build/runtime/build-runtime.js';
+import { ensureIntegrationRuntimeReady } from '../../../build/app-build-manifest-runtime.js';
+import { appLogger } from '../../../global/app-logger.js';
+import { copyRuntimePublicDirIfChanged } from './copy-runtime-public-dir.js';
+import { clearAppDevClientBridge } from '../../../dev/client-bridge-registry.js';
+import { clearAppHmrManager } from '../../../dev/hmr-manager-registry.js';
+/**
+ * Copies source `public/` into dist and ensures the resolved assets directory exists.
+ */
+export function prepareRuntimePublicDir(appConfig) {
+    const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+    if (fileSystem.exists(srcPublicDir)) {
+        copyRuntimePublicDirIfChanged(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+    }
+    fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+}
+const attachedHmrApps = new WeakSet();
+/**
+ * Attaches the shared HMR manager to every integration exactly once per app config.
+ *
+ * @remarks
+ * Runtime plugin setup must not call `integration.setHmrManager()` directly. Adapters invoke
+ * this after the manager is enabled so late plugin init cannot double-bind integrations.
+ */
+export function attachHmrToIntegrations(appConfig, hmrManager) {
+    if (attachedHmrApps.has(appConfig)) {
+        return;
+    }
+    attachedHmrApps.add(appConfig);
+    for (const integration of appConfig.integrations) {
+        integration.setHmrManager(hmrManager);
+    }
+}
+/**
+ * Starts background activation of every configured integration after watch-mode HMR is ready.
+ *
+ * @remarks
+ * Fire-and-forget: overlaps with watcher setup so first-page render can join the same
+ * coalesced {@link ensureIntegrationRuntimeReady} promise instead of paying a cold vendor build.
+ * Failures are logged and do not crash the server.
+ */
+export function startDevWarmup(options) {
+    const { appConfig, runtimeOrigin } = options;
+    void Promise.all(appConfig.integrations.map((integration) => ensureIntegrationRuntimeReady({
+        appConfig,
+        integrationName: integration.name,
+        runtimeOrigin,
+    }))).catch((error) => {
+        appLogger.error(`Failed to prewarm integration runtimes: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
+/**
+ * Releases shared dev resources in a consistent order across server adapters.
+ *
+ * @remarks
+ * Bun calls `buildRuntime()` during `initialize()` when watch is enabled; Node defers
+ * runtime creation to `completeInitialization()`. Transport-specific setup stays in
+ * each adapter — only shared teardown lives here.
+ */
+export async function disposeDevResources(options) {
+    await options.projectWatcher?.close();
+    await disposeAppBuildRuntime(options.appConfig);
+    options.hmrManager?.stop();
+    options.bridge?.destroy();
+    clearAppDevClientBridge(options.appConfig);
+    clearAppHmrManager(options.appConfig);
+    await options.previewHost.stop();
+}

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

@@ -1,18 +1,20 @@
-import { AbstractServerAdapter } from '../abstract/server-adapter.js';
-import type { ServerAdapterOptions, ServerAdapterResult } from '../abstract/server-adapter.js';
-import { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-import { RouteRegistry } from '../../router/server/route-registry.js';
-import { SchemaValidationService } from '../../services/validation/schema-validation-service.js';
-import { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
+import { AbstractServerAdapter } from '../../abstract/server-adapter.js';
+import type { ServerAdapterOptions, ServerAdapterResult } from '../../abstract/server-adapter.js';
+import { RouteRendererFactory } from '../../../route-renderer/route-renderer.js';
+import { RouteRegistry } from '../../../router/server/route-registry.js';
+import { SchemaValidationService } from '../../../services/validation/schema-validation-service.js';
+import { StaticSiteGenerator } from '../../../static-site-generator/static-site-generator.js';
 import { ServerStaticBuilder } from './server-static-builder.js';
-import { FileSystemResponseMatcher } from './fs-server-response-matcher.js';
+import { FileSystemResponseMatcher } from '../http/fs-server-response-matcher.js';
 import { ServerRouteHandler } from './server-route-handler.js';
-import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext, StaticRoute } from '../../types/public-types.js';
-type SharedRequestContext = {
+import { ApiRequestPipeline } from '../http/api-request-pipeline.js';
+import type { ApiHandler, CacheInvalidator, ErrorHandler, IHmrManager, RenderContext, StaticRoute } from '../../../types/public-types.js';
+type SharedHmrAssetManager = IHmrManager;
+type SharedRequestContext<TServer = unknown> = {
     apiHandlers: ApiHandler[];
-    errorHandler?: ErrorHandler;
-    serverInstance?: any;
-    hmrManager?: any;
+    errorHandler?: ErrorHandler<Request, TServer>;
+    serverInstance?: TServer;
+    hmrManager?: SharedHmrAssetManager;
 };
 export declare abstract class SharedServerAdapter<TOptions extends ServerAdapterOptions, TResult extends ServerAdapterResult> extends AbstractServerAdapter<TOptions, TResult> {
     protected router: RouteRegistry;
@@ -21,14 +23,23 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
     protected routeHandler: ServerRouteHandler;
     protected staticSiteGenerator: StaticSiteGenerator;
     protected staticBuilder: ServerStaticBuilder;
-    protected readonly schemaValidator: SchemaValidationService;
+    protected schemaValidator: SchemaValidationService;
+    protected readonly apiRequestPipeline: ApiRequestPipeline<Request, unknown>;
+    protected hostOwnsDevClient: boolean;
+    private devStaticRoutePrewarmStarted;
+    private sharedPageCacheService;
+    /**
+     * Warms declared static paths after the final watch-mode response pipeline exists.
+     */
+    protected startDevStaticRoutePrewarmWhenReady(): Promise<void>;
     protected initializeSharedRouteHandling(options: {
         staticRoutes: StaticRoute[];
-        hmrManager?: any;
+        hmrManager?: SharedHmrAssetManager;
     }): Promise<void>;
+    private ensureRouteRendererFactory;
     protected createSharedWatchRefreshCallback(options: {
         staticRoutes: StaticRoute[];
-        hmrManager?: any;
+        hmrManager?: SharedHmrAssetManager;
         onRoutesReady?: () => Promise<void> | void;
         onError?: (error: Error) => Promise<void> | void;
     }): () => Promise<void>;
@@ -50,54 +61,24 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
      * 2. How to match logical routes to physical filesystem artifacts via `FileSystemResponseMatcher`
      * 3. Whether to serve the response from the embedded `PageCacheService` or generate it fresh on the fly.
      *
-     * Because `HmrManager` implementations rely heavily on runtime-specific WebSocket APIs (e.g. Bun.serve Websockets vs Node WS),
-     * we leave it untyped (`any`) here at the common denominator core.
-     *
      * @param staticRoutes - A map of explicitly served static assets.
      * @param hmrManager - The runtime-specific Hot Module Replacement orchestrator (if watching).
      */
-    protected configureSharedResponseHandlers(staticRoutes: StaticRoute[], hmrManager?: any): void;
+    protected configureSharedResponseHandlers(staticRoutes: StaticRoute[], hmrManager?: IHmrManager): void;
     private createSharedResponseHandlerDependencies;
-    private createSharedPageCacheService;
+    private getOrCreateSharedPageCacheService;
     protected getCacheService(): CacheInvalidator | null;
     protected getRenderContext(): RenderContext;
-    /**
-     * Executes an Application Programming Interface (API) handler in an environment-agnostic manner.
-     *
-     * API routes in Ecopages are universally written using standard WinterCG `Request` and `Response` objects.
-     * This execution pipeline takes the raw `Request`, extracts its dynamic segments, runs our high-speed JSON schema
-     * validator against the body/query/headers, and triggers the developer's middleware chain sequentially.
-     *
-     * If the execution throws an error, it is gracefully caught, logged, and mutated into a standardized Http error payload,
-     * ensuring the consuming client receives a parsable response even upon internal catastrophic failure.
-     *
-     * @param request - The incoming Web standard `Request`.
-     * @param params - The extracted dynamic URL parameters (e.g., `{ id: '123' }`).
-     * @param routeConfig - The user-defined API handler object containing their business logic (`handler`) and `middleware`.
-     * @param serverInstance - Untyped reference to the underlying native server instance (BunServer/NodeServer) for potential escape hatches.
-     * @param errorHandler - Optional global error trap defined in project configuration.
-     * @returns The resulting Web standard `Response` constructed by the user's handler.
-     */
-    protected executeApiHandler(request: Request, params: Record<string, string | string[]>, routeConfig: ApiHandler, serverInstance: any, errorHandler?: ErrorHandler): Promise<Response>;
-    private createApiHandlerContext;
-    private normalizeApiParams;
-    private applyApiRequestSchema;
-    private runApiMiddlewareChain;
-    private normalizePath;
-    private matchApiPath;
-    private getApiPathScore;
-    protected matchApiHandler(request: Request, apiHandlers: ApiHandler[]): {
-        routeConfig: ApiHandler;
-        params: Record<string, string | string[]>;
-    } | null;
+    private tryHandleSharedDevClientRequest;
     private tryHandleSharedHmrRequest;
+    private injectSharedHmrHtmlResponse;
     private tryHandleSharedApiRequest;
     /**
      * Universally processes an incoming WinterCG Web standard Request.
      *
      * 1. Resolves static Hot Module Replacement runtime blobs if development.
      * 2. Checks if the incoming request matches any parsed API route schemas.
-     *   - Routes through `executeApiHandler` which performs strict validation.
+     *   - Routes through `ApiRequestPipeline` which performs strict validation.
      * 3. Falls through to standard `ServerRouteHandler` for React/Lit filesystem pages.
      *
      * Both Bun and Node bindings fall back to this exact function once they have mapped their

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

@@ -0,0 +1,301 @@
+import path from 'node:path';
+import { AbstractServerAdapter } from '../../abstract/server-adapter.js';
+import { RouteRendererFactory } from '../../../route-renderer/route-renderer.js';
+import { RouteRegistry } from '../../../router/server/route-registry.js';
+import { startupTrace } from '../../../diagnostics/startup-trace.js';
+import { requestBuildDedupe } from '../../../diagnostics/request-build-dedupe.js';
+import { MemoryCacheStore } from '../../../services/cache/memory-cache-store.js';
+import { PageCacheService, registerAppPageCacheService } from '../../../services/cache/page-cache-service.js';
+import { SchemaValidationService } from '../../../services/validation/schema-validation-service.js';
+import { StaticSiteGenerator } from '../../../static-site-generator/static-site-generator.js';
+import { ServerStaticBuilder } from './server-static-builder.js';
+import { ExplicitStaticRouteMatcher } from '../http/explicit-static-route-matcher.js';
+import { FileSystemServerResponseFactory } from '../http/fs-server-response-factory.js';
+import { FileSystemResponseMatcher } from '../http/fs-server-response-matcher.js';
+import { ServerRouteHandler } from './server-route-handler.js';
+import { startDevStaticRoutePrewarm, runDevStaticRoutePrewarm } from './dev-static-route-prewarm.js';
+import { collectAppDevPrewarmPlan } from './collect-dev-prewarm-plan.js';
+import { createRenderContext } from './render-context.js';
+import { ApiRequestPipeline } from '../http/api-request-pipeline.js';
+import { injectDevToolbarIntoHtmlResponse, shouldInjectDevToolbarHtmlResponse, } from '../../../dev-toolbar/dev-toolbar-html-response.js';
+import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse, } from '../hmr/hmr-html-response.js';
+import { getAppServerModuleTranspiler } from '../../../services/module-loading/app-server-module-transpiler.service.js';
+import { resolveInternalExecutionDir } from '../../../utils/resolve-work-dir.js';
+export class SharedServerAdapter extends AbstractServerAdapter {
+    router;
+    fileSystemResponseMatcher;
+    routeRendererFactory;
+    routeHandler;
+    staticSiteGenerator;
+    staticBuilder;
+    schemaValidator = new SchemaValidationService();
+    apiRequestPipeline = new ApiRequestPipeline({
+        schemaValidator: this.schemaValidator,
+        getRenderContext: () => this.getRenderContext(),
+        getCacheService: () => this.getCacheService(),
+    });
+    hostOwnsDevClient = false;
+    devStaticRoutePrewarmStarted = false;
+    sharedPageCacheService;
+    /**
+     * Warms declared static paths after the final watch-mode response pipeline exists.
+     */
+    async startDevStaticRoutePrewarmWhenReady() {
+        if (!this.options?.watch || this.devStaticRoutePrewarmStarted) {
+            return;
+        }
+        this.devStaticRoutePrewarmStarted = true;
+        const runtimeOrigin = this.runtimeOrigin;
+        const plan = await collectAppDevPrewarmPlan(this.appConfig);
+        const beforeReadyPathnames = new Set(plan.beforeReadyPathnames);
+        const allPathnames = plan.pathnames;
+        const options = {
+            pathnames: allPathnames,
+            readiness: 'background',
+            renderPath: async (pathname) => {
+                const response = await this.routeHandler.handleResponse(new Request(new URL(pathname, runtimeOrigin).toString(), { method: 'GET' }));
+                await response.arrayBuffer();
+            },
+        };
+        if (beforeReadyPathnames.size > 0) {
+            await runDevStaticRoutePrewarm({
+                ...options,
+                pathnames: [...beforeReadyPathnames],
+                readiness: 'beforeReady',
+            });
+        }
+        const backgroundPathnames = allPathnames.filter((pathname) => !beforeReadyPathnames.has(pathname));
+        if (backgroundPathnames.length > 0) {
+            startDevStaticRoutePrewarm({ ...options, pathnames: backgroundPathnames });
+        }
+    }
+    async initializeSharedRouteHandling(options) {
+        this.ensureRouteRendererFactory();
+        await this.initSharedRouter();
+        this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
+    }
+    ensureRouteRendererFactory() {
+        if (this.routeRendererFactory) {
+            return;
+        }
+        this.routeRendererFactory = new RouteRendererFactory({
+            appConfig: this.appConfig,
+            rendererModules: this.appConfig.runtime?.rendererModuleContext,
+            runtimeOrigin: this.runtimeOrigin,
+        });
+    }
+    createSharedWatchRefreshCallback(options) {
+        return async () => {
+            try {
+                await this.initializeSharedRouteHandling({
+                    staticRoutes: options.staticRoutes,
+                    hmrManager: options.hmrManager,
+                });
+                if (options.onRoutesReady) {
+                    await options.onRoutesReady();
+                }
+            }
+            catch (error) {
+                if (options.onError) {
+                    await options.onError(error instanceof Error ? error : new Error(String(error)));
+                    return;
+                }
+                throw error;
+            }
+        };
+    }
+    /**
+     * Scans the filesystem and dynamically constructs the Route Registry.
+     *
+     * This process runs identically across both Bun and Node wrappers. It analyzes the configured pages
+     * directory, building a map of all available UI routes and API endpoints.
+     * The resulting `RouteRegistry` instance becomes the central nervous system for mapping WinterCG incoming
+     * Web Requests (`Request`) to their corresponding internal execution paths.
+     */
+    async initSharedRouter() {
+        startupTrace.markPhaseStart('route-registry');
+        this.router = new RouteRegistry({
+            pagesDir: path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.pagesDir),
+            appConfig: this.appConfig,
+            origin: this.runtimeOrigin,
+            templatesExt: this.appConfig.templatesExt,
+            buildMode: !this.options?.watch,
+            pageModuleAdapter: this.createRouteRegistryPageModuleAdapter(),
+        });
+        await this.router.init();
+        startupTrace.markPhaseEnd('route-registry');
+    }
+    createRouteRegistryPageModuleAdapter() {
+        this.ensureRouteRendererFactory();
+        return {
+            loadPageModule: async (filePath) => {
+                const module = (await this.routeRendererFactory
+                    .getPageRenderer(filePath)
+                    .loadPageModule(filePath));
+                const page = module.default;
+                return {
+                    staticPaths: page?.staticPaths ?? module.getStaticPaths,
+                    staticProps: page?.staticProps ?? module.getStaticProps,
+                };
+            },
+        };
+    }
+    /**
+     * Sets up the unified rendering pipeline and response matching chain.
+     *
+     * It bridges several sub-systems together so that when an incoming request is received, the adapter knows:
+     * 1. How to render React/Lit pages via `RouteRendererFactory`
+     * 2. How to match logical routes to physical filesystem artifacts via `FileSystemResponseMatcher`
+     * 3. Whether to serve the response from the embedded `PageCacheService` or generate it fresh on the fly.
+     *
+     * @param staticRoutes - A map of explicitly served static assets.
+     * @param hmrManager - The runtime-specific Hot Module Replacement orchestrator (if watching).
+     */
+    configureSharedResponseHandlers(staticRoutes, hmrManager) {
+        this.ensureRouteRendererFactory();
+        const { fileSystemResponseMatcher, explicitStaticRouteMatcher } = this.createSharedResponseHandlerDependencies(staticRoutes);
+        this.fileSystemResponseMatcher = fileSystemResponseMatcher;
+        this.routeHandler = new ServerRouteHandler({
+            router: this.router,
+            fileSystemResponseMatcher: this.fileSystemResponseMatcher,
+            explicitStaticRouteMatcher,
+            hmrManager,
+        });
+    }
+    createSharedResponseHandlerDependencies(staticRoutes) {
+        const fileSystemResponseFactory = new FileSystemServerResponseFactory({
+            options: {
+                watchMode: !!this.options?.watch,
+            },
+        });
+        const cacheService = this.getOrCreateSharedPageCacheService();
+        const fileSystemResponseMatcher = new FileSystemResponseMatcher({
+            appConfig: this.appConfig,
+            assetPrefix: path.join(this.appConfig.rootDir, this.appConfig.distDir),
+            router: this.router,
+            routeRendererFactory: this.routeRendererFactory,
+            fileSystemResponseFactory,
+            cacheService,
+            defaultCacheStrategy: this.appConfig.cache?.defaultStrategy ?? 'static',
+        });
+        return {
+            cacheService,
+            fileSystemResponseMatcher,
+            explicitStaticRouteMatcher: staticRoutes.length > 0
+                ? new ExplicitStaticRouteMatcher({
+                    appConfig: this.appConfig,
+                    routeRendererFactory: this.routeRendererFactory,
+                    staticRoutes,
+                })
+                : undefined,
+        };
+    }
+    getOrCreateSharedPageCacheService() {
+        if (this.sharedPageCacheService !== undefined) {
+            return this.sharedPageCacheService;
+        }
+        const cacheConfig = this.appConfig.cache;
+        const watch = Boolean(this.options?.watch);
+        if (watch) {
+            if (cacheConfig?.enabled === false) {
+                this.sharedPageCacheService = null;
+                registerAppPageCacheService(this.appConfig, null);
+                return null;
+            }
+            const store = cacheConfig?.store === 'memory' || !cacheConfig?.store
+                ? new MemoryCacheStore({ maxEntries: cacheConfig?.maxEntries })
+                : cacheConfig.store;
+            const service = new PageCacheService({ store, enabled: true });
+            this.sharedPageCacheService = service;
+            registerAppPageCacheService(this.appConfig, service);
+            return service;
+        }
+        const isCacheEnabled = cacheConfig?.enabled ?? true;
+        if (!isCacheEnabled) {
+            this.sharedPageCacheService = null;
+            registerAppPageCacheService(this.appConfig, null);
+            return null;
+        }
+        const store = cacheConfig?.store === 'memory' || !cacheConfig?.store
+            ? new MemoryCacheStore({ maxEntries: cacheConfig?.maxEntries })
+            : cacheConfig.store;
+        const service = new PageCacheService({ store, enabled: true });
+        this.sharedPageCacheService = service;
+        registerAppPageCacheService(this.appConfig, service);
+        return service;
+    }
+    getCacheService() {
+        return this.fileSystemResponseMatcher?.getCacheService() ?? null;
+    }
+    getRenderContext() {
+        const serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+        return createRenderContext({
+            integrations: this.appConfig.integrations,
+            rendererModules: this.appConfig.runtime?.rendererModuleContext,
+            importServerModule: async (filePath) => await serverModuleTranspiler.importModule({
+                filePath,
+                outdir: path.join(resolveInternalExecutionDir(this.appConfig), '.server-modules'),
+                externalPackages: true,
+            }),
+        });
+    }
+    async tryHandleSharedDevClientRequest(request, context) {
+        const manager = context.hmrManager;
+        return (await manager?.tryHandleDevClientRequest?.(request)) ?? null;
+    }
+    tryHandleSharedHmrRequest(request, context) {
+        return context.hmrManager?.tryHandleAssetRequest(request) ?? null;
+    }
+    async injectSharedHmrHtmlResponse(response, context) {
+        if (!isHtmlResponse(response)) {
+            return response;
+        }
+        let nextResponse = response;
+        if (shouldInjectHmrHtmlResponse(this.options?.watch ?? false, context.hmrManager, this.hostOwnsDevClient) &&
+            isHtmlResponse(nextResponse)) {
+            nextResponse = await injectHmrRuntimeIntoHtmlResponse(nextResponse);
+        }
+        if (shouldInjectDevToolbarHtmlResponse(this.appConfig, {
+            watch: this.options?.watch ?? false,
+            hostOwnsDevClient: this.hostOwnsDevClient,
+        })) {
+            nextResponse = await injectDevToolbarIntoHtmlResponse(this.appConfig, {
+                watch: this.options?.watch ?? false,
+                hostOwnsDevClient: this.hostOwnsDevClient,
+            }, nextResponse);
+        }
+        return nextResponse;
+    }
+    async tryHandleSharedApiRequest(request, context) {
+        return await this.apiRequestPipeline.tryHandle(request, context.apiHandlers, context.serverInstance, context.errorHandler);
+    }
+    /**
+     * Universally processes an incoming WinterCG Web standard Request.
+     *
+     * 1. Resolves static Hot Module Replacement runtime blobs if development.
+     * 2. Checks if the incoming request matches any parsed API route schemas.
+     *   - Routes through `ApiRequestPipeline` which performs strict validation.
+     * 3. Falls through to standard `ServerRouteHandler` for React/Lit filesystem pages.
+     *
+     * Both Bun and Node bindings fall back to this exact function once they have mapped their
+     * native HTTP objects into Web Standard Requests.
+     */
+    async handleSharedRequest(request, context) {
+        return requestBuildDedupe.run(() => startupTrace.traceFirstRequest(request, async () => {
+            const devClientResponse = await this.tryHandleSharedDevClientRequest(request, context);
+            if (devClientResponse) {
+                return devClientResponse;
+            }
+            const hmrResponse = this.tryHandleSharedHmrRequest(request, context);
+            if (hmrResponse) {
+                return hmrResponse;
+            }
+            const apiResponse = await this.tryHandleSharedApiRequest(request, context);
+            if (apiResponse) {
+                return await this.injectSharedHmrHtmlResponse(apiResponse, context);
+            }
+            const routeResponse = await this.routeHandler.handleResponse(request);
+            return await this.injectSharedHmrHtmlResponse(routeResponse, context);
+        }));
+    }
+}

package/src/adapters/shared/{server-route-handler.d.ts → runtime/server-route-handler.d.ts}

@@ -1,7 +1,7 @@
-import type { IHmrManager } from '../../types/public-types.js';
-import type { RouteRegistry } from '../../router/server/route-registry.js';
-import type { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher.js';
-import type { FileSystemResponseMatcher } from './fs-server-response-matcher.js';
+import type { IHmrManager } from '../../../types/public-types.js';
+import type { RouteRegistry } from '../../../router/server/route-registry.js';
+import type { ExplicitStaticRouteMatcher } from '../http/explicit-static-route-matcher.js';
+import type { FileSystemResponseMatcher } from '../http/fs-server-response-matcher.js';
 /**
  * Configuration parameters for ServerRouteHandler.
  */
@@ -12,8 +12,6 @@ export interface ServerRouteHandlerParams {
     fileSystemResponseMatcher: FileSystemResponseMatcher;
     /** Optional matcher for explicit static routes like processed images or sitemaps. */
     explicitStaticRouteMatcher?: ExplicitStaticRouteMatcher;
-    /** Enable watch mode for development. */
-    watch?: boolean;
     /** HMR manager for broadcasting hot module reload events in development. */
     hmrManager?: IHmrManager;
 }
@@ -25,33 +23,18 @@ export interface ServerRouteHandlerParams {
  * 2. File-based routes without extensions (application routes)
  * 3. Static file fallback (lowest priority - disk serving)
  *
- * In development mode, it also injects HMR scripts into HTML responses.
  */
 export declare class ServerRouteHandler {
     private readonly router;
     private readonly fileSystemResponseMatcher;
     private readonly explicitStaticRouteMatcher?;
-    private readonly watch;
     private readonly hmrManager?;
     /**
      * Creates a new ServerRouteHandler instance.
      *
      * @param params - Configuration parameters
      */
-    constructor({ router, fileSystemResponseMatcher, explicitStaticRouteMatcher, watch, hmrManager, }: ServerRouteHandlerParams);
-    /**
-     * Determines if HMR script should be injected.
-     *
-     * @returns true if in watch mode and HMR manager is enabled
-     */
-    shouldInjectHmrScript(): boolean;
-    /**
-     * Checks if a response contains HTML content.
-     *
-     * @param response - The HTTP response to check
-     * @returns true if Content-Type header starts with 'text/html'
-     */
-    isHtmlResponse(response: Response): boolean;
+    constructor({ router, fileSystemResponseMatcher, explicitStaticRouteMatcher, hmrManager, }: ServerRouteHandlerParams);
     /**
      * Handles HTTP requests from the router adapter.
      *
@@ -61,19 +44,9 @@ export declare class ServerRouteHandler {
      * 3. Fall back to static file serving from disk
      *
      * @param request - The incoming HTTP request
-     * @returns HTTP response, potentially with injected HMR script in dev mode
+     * @returns HTTP response for the matched route
      */
     handleResponse(request: Request): Promise<Response>;
-    /**
-     * Injects HMR script into HTML responses in development mode.
-     *
-     * The script is inserted before the closing </html> tag to enable
-     * hot module reloading without full page refreshes.
-     *
-     * @param response - The HTTP response to potentially modify
-     * @returns Original response or modified response with HMR script
-     */
-    private maybeInjectHmrScript;
     /**
      * Handles requests that do not match any routes.
      *

package/src/adapters/shared/runtime/server-route-handler.js

@@ -0,0 +1,77 @@
+import { appLogger } from '../../../global/app-logger.js';
+import { HttpError } from '../../../errors/http-error.js';
+/**
+ * Handles HTTP requests and routing for the server.
+ *
+ * This class manages the request routing flow with a priority-based approach:
+ * 1. Explicit static routes (highest priority - intentional mappings like /sitemap.xml)
+ * 2. File-based routes without extensions (application routes)
+ * 3. Static file fallback (lowest priority - disk serving)
+ *
+ */
+export class ServerRouteHandler {
+    router;
+    fileSystemResponseMatcher;
+    explicitStaticRouteMatcher;
+    hmrManager;
+    /**
+     * Creates a new ServerRouteHandler instance.
+     *
+     * @param params - Configuration parameters
+     */
+    constructor({ router, fileSystemResponseMatcher, explicitStaticRouteMatcher, hmrManager, }) {
+        this.router = router;
+        this.fileSystemResponseMatcher = fileSystemResponseMatcher;
+        this.explicitStaticRouteMatcher = explicitStaticRouteMatcher;
+        this.hmrManager = hmrManager;
+    }
+    /**
+     * Handles HTTP requests from the router adapter.
+     *
+     * Priority-based routing flow:
+     * 1. Check explicit static routes first (e.g., /sitemap.xml, /image.webp from plugins)
+     * 2. Match file-based routes without extensions (application routes)
+     * 3. Fall back to static file serving from disk
+     *
+     * @param request - The incoming HTTP request
+     * @returns HTTP response for the matched route
+     */
+    async handleResponse(request) {
+        const pathname = new URL(request.url).pathname;
+        const explicitMatch = this.explicitStaticRouteMatcher?.match(request.url);
+        if (explicitMatch) {
+            return await this.explicitStaticRouteMatcher.handleMatch(explicitMatch);
+        }
+        const fsMatch = !pathname.includes('.') && this.router.matchRequest(request.url);
+        return await (fsMatch
+            ? this.fileSystemResponseMatcher.handleMatch(fsMatch, request)
+            : this.handleNoMatch(request));
+    }
+    /**
+     * Handles requests that do not match any routes.
+     *
+     * This is the final fallback that attempts to serve static files from disk.
+     * If the requested path corresponds to an HTML file or no file is found,
+     * a custom 404 response is returned.
+     *
+     * @param request - The HTTP request to handle
+     * @returns Response from file system or error response
+     * @throws HttpError for standard HTTP errors
+     */
+    async handleNoMatch(request) {
+        try {
+            const pathname = new URL(request.url).pathname;
+            return await this.fileSystemResponseMatcher.handleNoMatch(pathname);
+        }
+        catch (error) {
+            if (error instanceof HttpError) {
+                return error.toResponse();
+            }
+            if (error instanceof Error) {
+                this.hmrManager?.broadcast({ type: 'error', message: error.message });
+                appLogger.error('Error handling no match:', error);
+            }
+            return new Response('Internal Server Error', { status: 500 });
+        }
+    }
+}