@ecopages/core 0.2.0-beta.29 → 0.2.0-beta.30

package/src/adapters/shared/{render-context.d.ts → runtime/render-context.d.ts}

@@ -1,5 +1,5 @@
-import type { RenderContext } from '../../types/public-types.js';
-import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
+import type { RenderContext } from '../../../types/public-types.js';
+import type { AnyIntegrationPlugin } from '../../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
     integrations: AnyIntegrationPlugin[];
     rendererModules?: unknown;

package/src/adapters/shared/{render-context.js → runtime/render-context.js}

@@ -1,5 +1,6 @@
 import { fileURLToPath } from "node:url";
-import { invariant } from "../../utils/invariant.js";
+import { invariant } from "../../../utils/invariant.js";
+import { createBodyResponse } from "../http/create-body-response.js";
 function resolveServerModulePath(filePath) {
   return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
 }
@@ -64,25 +65,15 @@ function createRenderContext(options) {
       return renderer.renderToResponse(view, mergedProps, ctx);
     },
     json(data, responseOptions) {
-      const headers = new Headers({ "Content-Type": "application/json; charset=utf-8" });
-      if (responseOptions?.headers) {
-        const incomingHeaders = new Headers(responseOptions.headers);
-        incomingHeaders.forEach((value, key) => headers.set(key, value));
-      }
-      return new Response(JSON.stringify(data), {
-        status: responseOptions?.status ?? 200,
-        headers
+      return createBodyResponse("json", data, {
+        status: responseOptions?.status,
+        headers: responseOptions?.headers
       });
     },
     html(content, responseOptions) {
-      const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
-      if (responseOptions?.headers) {
-        const incomingHeaders = new Headers(responseOptions.headers);
-        incomingHeaders.forEach((value, key) => headers.set(key, value));
-      }
-      return new Response(content, {
-        status: responseOptions?.status ?? 200,
-        headers
+      return createBodyResponse("html", content, {
+        status: responseOptions?.status,
+        headers: responseOptions?.headers
       });
     }
   };

package/src/adapters/shared/{runtime-app-bootstrap.d.ts → runtime/runtime-app-bootstrap.d.ts}

@@ -1,5 +1,5 @@
-import type { ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ReturnParseCliArgs } from '../../../utils/parse-cli-args.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
 export type RuntimeBinding = {
     preferredPort: number;
     preferredHostname: string;

package/src/adapters/shared/{runtime-app-bootstrap.js → runtime/runtime-app-bootstrap.js}

@@ -1,4 +1,4 @@
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../../config/constants.js";
 function normalizeOriginHostname(hostname) {
   if (hostname.includes(":") && !hostname.startsWith("[") && !hostname.endsWith("]")) {
     return `[${hostname}]`;

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

@@ -1,6 +1,6 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { IHmrManager } from '../../types/public-types.js';
-import type { ProjectWatcher } from '../../watchers/project-watcher.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { IHmrManager } from '../../../types/public-types.js';
+import type { ProjectWatcher } from '../../../watchers/project-watcher.js';
 /**
  * Copies source `public/` into dist and ensures the resolved assets directory exists.
  */
@@ -14,17 +14,17 @@ export declare function prepareRuntimePublicDir(appConfig: EcoPagesAppConfig): v
  */
 export declare function attachHmrToIntegrations(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
 /**
- * @deprecated Use {@link attachHmrToIntegrations} instead.
- */
-export declare function wireIntegrationHmrManagers(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
-/**
- * Injects the dev HMR runtime into adapter-level HTML responses when watch mode is active.
+ * 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 declare function maybeInjectAdapterHmrHtmlResponse(response: Response, options: {
-    watch: boolean;
-    hmrManager?: Pick<IHmrManager, 'isEnabled'>;
-    hostOwnsDevClient: boolean;
-}): Promise<Response>;
+export declare function startConfiguredIntegrationRuntimePrewarm(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+}): void;
 /**
  * Releases shared dev resources in a consistent order across server adapters.
  *

package/src/adapters/shared/{runtime-server-lifecycle.js → runtime/runtime-server-lifecycle.js}

@@ -1,11 +1,12 @@
 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 { 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";
-import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from "./hmr-html-response.js";
+import { clearAppDevClientBridge } from "../../../dev/client-bridge-registry.js";
+import { clearAppHmrManager } from "../../../dev/hmr-manager-registry.js";
 function prepareRuntimePublicDir(appConfig) {
   const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
   if (fileSystem.exists(srcPublicDir)) {
@@ -23,14 +24,21 @@ function attachHmrToIntegrations(appConfig, hmrManager) {
     integration.setHmrManager(hmrManager);
   }
 }
-function wireIntegrationHmrManagers(appConfig, hmrManager) {
-  attachHmrToIntegrations(appConfig, hmrManager);
-}
-async function maybeInjectAdapterHmrHtmlResponse(response, options) {
-  if (shouldInjectHmrHtmlResponse(options.watch, options.hmrManager, options.hostOwnsDevClient) && isHtmlResponse(response)) {
-    return injectHmrRuntimeIntoHtmlResponse(response);
-  }
-  return response;
+function startConfiguredIntegrationRuntimePrewarm(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)}`
+    );
+  });
 }
 async function disposeDevResources(options) {
   await options.projectWatcher?.close();
@@ -44,7 +52,6 @@ async function disposeDevResources(options) {
 export {
   attachHmrToIntegrations,
   disposeDevResources,
-  maybeInjectAdapterHmrHtmlResponse,
   prepareRuntimePublicDir,
-  wireIntegrationHmrManagers
+  startConfiguredIntegrationRuntimePrewarm
 };

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;
@@ -22,15 +24,16 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
     protected staticSiteGenerator: StaticSiteGenerator;
     protected staticBuilder: ServerStaticBuilder;
     protected schemaValidator: SchemaValidationService;
+    protected readonly apiRequestPipeline: ApiRequestPipeline<Request, unknown>;
     protected hostOwnsDevClient: boolean;
     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>;
@@ -52,54 +55,23 @@ 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;
     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 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,226 @@
+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 } 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 { createRenderContext } from "./render-context.js";
+import { ApiRequestPipeline } from "../http/api-request-pipeline.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";
+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;
+  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.createSharedPageCacheService();
+    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
+      }) : void 0
+    };
+  }
+  createSharedPageCacheService() {
+    const cacheConfig = this.appConfig.cache;
+    const isCacheEnabled = cacheConfig?.enabled ?? !this.options?.watch;
+    if (!isCacheEnabled) {
+      return null;
+    }
+    const store = cacheConfig?.store === "memory" || !cacheConfig?.store ? new MemoryCacheStore({ maxEntries: cacheConfig?.maxEntries }) : cacheConfig.store;
+    return new PageCacheService({ store, enabled: true });
+  }
+  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
+      })
+    });
+  }
+  tryHandleSharedHmrRequest(request, context) {
+    return context.hmrManager?.tryHandleAssetRequest(request) ?? null;
+  }
+  async injectSharedHmrHtmlResponse(response, context) {
+    if (shouldInjectHmrHtmlResponse(this.options?.watch ?? false, context.hmrManager, this.hostOwnsDevClient) && isHtmlResponse(response)) {
+      return injectHmrRuntimeIntoHtmlResponse(response);
+    }
+    return response;
+  }
+  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 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);
+      })
+    );
+  }
+}
+export {
+  SharedServerAdapter
+};

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,12 +12,8 @@ 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;
-    /** When true, the host dev server owns browser dev-client bootstrap. */
-    hostOwnsDevClient?: boolean;
 }
 /**
  * Handles HTTP requests and routing for the server.
@@ -27,34 +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?;
-    private readonly hostOwnsDevClient;
     /**
      * Creates a new ServerRouteHandler instance.
      *
      * @param params - Configuration parameters
      */
-    constructor({ router, fileSystemResponseMatcher, explicitStaticRouteMatcher, watch, hmrManager, hostOwnsDevClient, }: 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.
      *
@@ -64,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.
      *