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

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

@@ -1,52 +1,51 @@
 import path from "node:path";
 import { appLogger } from "../../global/app-logger.js";
-import { PageModuleImportService } from "../../services/page-module-import.service.js";
-import { PageRequestCacheCoordinator } from "../../services/page-request-cache-coordinator.service.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 { LocalsAccessError } from "../../errors/locals-access-error.js";
 import { isDevelopmentRuntime } from "../../utils/runtime.js";
-const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS = {
-  transpilePageModuleFailed: (details) => `Error transpiling page module: ${details}`,
-  noTranspiledOutputForPageModule: (filePath) => `No transpiled output generated for page module: ${filePath}`
-};
 class FileSystemResponseMatcher {
+  appConfig;
+  assetPrefix;
   router;
   routeRendererFactory;
   fileSystemResponseFactory;
-  pageModuleImportService;
   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.pageModuleImportService = new PageModuleImportService();
     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.hasKnownExtension(requestUrl);
     if (!isStaticFileRequest) {
-      return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+      return this.renderCustomNotFoundResponse();
     }
     const relativeUrl = requestUrl.startsWith("/") ? requestUrl.slice(1) : requestUrl;
-    const filePath = path.join(this.router.assetPrefix, relativeUrl);
+    const filePath = path.join(this.assetPrefix, relativeUrl);
     const contentType = ServerUtils.getContentType(filePath);
-    return this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+    const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+    return response ?? this.renderCustomNotFoundResponse();
   }
   /**
    * Handles a matched file-system page route.
@@ -60,34 +59,25 @@ class FileSystemResponseMatcher {
    * @returns Final response for the matched route.
    */
   async handleMatch(match, request) {
-    const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey(match);
     try {
-      const resolvedRequest = request ?? new Request(new URL(cacheKey, this.router.origin).toString(), {
-        method: "GET"
-      });
-      const localsStore = {};
-      const pageModule = await this.importPageModule(match.filePath);
-      const Page = pageModule?.default;
-      const pageMiddleware = Page?.middleware ?? [];
-      const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-      const localsForRender = pageCacheStrategy === "dynamic" ? localsStore : void 0;
+      const executionPlan = await this.createExecutionPlan(match, request);
       this.fileRouteMiddlewarePipeline.assertValidConfiguration({
-        middleware: pageMiddleware,
-        pageCacheStrategy,
-        filePath: match.filePath
+        middleware: executionPlan.pageMiddleware,
+        pageCacheStrategy: executionPlan.pageCacheStrategy,
+        filePath: executionPlan.pageFilePath
       });
-      const routeRenderer = this.routeRendererFactory.createRenderer(match.filePath);
+      const routeRenderer = this.routeRendererFactory.getPageRenderer(executionPlan.pageFilePath);
       const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
-        request: resolvedRequest,
+        request: executionPlan.request,
         params: match.params,
-        locals: localsStore
+        locals: executionPlan.localsStore
       });
       const renderFn = async () => {
-        const result = await routeRenderer.createRoute({
-          file: match.filePath,
+        const result = await routeRenderer.execute({
+          file: executionPlan.pageFilePath,
           params: match.params,
           query: match.query,
-          locals: localsForRender
+          locals: executionPlan.localsForRender
         });
         const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
         const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
@@ -95,13 +85,13 @@ class FileSystemResponseMatcher {
       };
       const renderResponse = async () => {
         return this.pageRequestCacheCoordinator.render({
-          cacheKey,
-          pageCacheStrategy,
+          cacheKey: executionPlan.cacheKey,
+          pageCacheStrategy: executionPlan.pageCacheStrategy,
           renderFn
         });
       };
       return await this.fileRouteMiddlewarePipeline.run({
-        middleware: pageMiddleware,
+        middleware: executionPlan.pageMiddleware,
         context: middlewareContext,
         renderResponse
       });
@@ -117,29 +107,71 @@ class FileSystemResponseMatcher {
       }
       if (error instanceof Error) {
         if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.pathname}`);
+          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.requestedPathname}`);
         }
       }
-      return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+      return this.renderCustomNotFoundResponse();
+    }
+  }
+  /**
+   * Renders the app-owned custom 404 page, falling back to the default text 404
+   * when the page template cannot be resolved.
+   */
+  async renderCustomNotFoundResponse() {
+    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+    try {
+      const routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
+      const result = await routeRenderer.execute({
+        file: error404TemplatePath
+      });
+      return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+    } catch {
+      appLogger.debug(
+        "Custom 404 template not found, falling back to default 404 response",
+        error404TemplatePath
+      );
+      return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
     }
   }
+  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 Page = pageModule?.default;
+    const pageMiddleware = Page?.middleware ?? [];
+    const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+    return {
+      cacheKey,
+      request: resolvedRequest,
+      pageFilePath,
+      pageMiddleware,
+      pageCacheStrategy,
+      localsStore,
+      localsForRender: pageCacheStrategy === "dynamic" ? localsStore : void 0
+    };
+  }
   /**
    * 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 uses the shared module
-   * import service directly rather than going through route rendering.
+   * `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) {
-    return this.pageModuleImportService.importModule({
-      filePath,
-      rootDir: path.dirname(this.router.assetPrefix),
-      outdir: path.join(this.router.assetPrefix, ".server-modules-meta"),
-      transpileErrorMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.transpilePageModuleFailed,
-      noOutputMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.noTranspiledOutputForPageModule
+    const routeRenderer = this.routeRendererFactory.getPageRenderer(filePath);
+    return routeRenderer.loadPageModule(filePath, {
+      cacheScope: "request-metadata"
     });
   }
   /**
@@ -150,6 +182,5 @@ class FileSystemResponseMatcher {
   }
 }
 export {
-  FILE_SYSTEM_RESPONSE_MATCHER_ERRORS,
   FileSystemResponseMatcher
 };

package/src/adapters/shared/hmr-entrypoint-registrar.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared runtime state used while registering HMR-owned entrypoints.
+ */
+export interface HmrEntrypointRegistrarOptions {
+    /** Absolute source directory used to derive the emitted HMR path. */
+    srcDir: string;
+    /** Absolute distribution directory where HMR outputs are written. */
+    distDir: string;
+    /** In-flight registrations keyed by normalized absolute entrypoint path. */
+    entrypointRegistrations: Map<string, Promise<string>>;
+    /** Stable entrypoint-to-output mapping retained once an entrypoint is registered. */
+    watchedFiles: Map<string, string>;
+    /** Runtime-specific cleanup invoked when an entrypoint registration fails. */
+    clearFailedRegistration?: (entrypointPath: string) => void;
+    /** Development-only guardrail for integrations that never finish producing output. */
+    registrationTimeoutMs: number;
+}
+/**
+ * Runtime-specific hooks required to materialize a single HMR entrypoint.
+ */
+export interface HmrEntrypointRegistrationOptions {
+    /**
+     * Emits the browser-consumable HMR artifact for an entrypoint.
+     */
+    emit(entrypointPath: string, outputPath: string): Promise<void>;
+    /**
+     * Creates the runtime-specific error raised when the emit hook completes without producing output.
+     */
+    getMissingOutputError(entrypointPath: string, outputPath: string): Error;
+}
+/**
+ * Coordinates the shared HMR entrypoint registration lifecycle for both Node and Bun managers.
+ *
+ * The registrar owns the cross-runtime policy: normalize entrypoint identities, dedupe concurrent
+ * registrations, derive the emitted `_hmr` output path, clear stale output before rebuilding, and
+ * apply the development timeout that prevents unresolved registrations from hanging navigation.
+ * Runtime-specific managers remain responsible for the actual emit step and any cleanup outside
+ * this shared registration flow.
+ */
+export declare class HmrEntrypointRegistrar {
+    private readonly options;
+    constructor(options: HmrEntrypointRegistrarOptions);
+    /**
+     * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+     *
+     * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
+     * integration only builds once per registration cycle.
+     */
+    registerEntrypoint(entrypointPath: string, registrationOptions: HmrEntrypointRegistrationOptions): Promise<string>;
+    private registerEntrypointInternal;
+    private awaitEntrypointRegistration;
+    private getEntrypointOutput;
+    private removeStaleEntrypointOutput;
+    private encodeDynamicSegments;
+}

package/src/adapters/shared/hmr-entrypoint-registrar.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../../global/app-logger.js";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+class HmrEntrypointRegistrar {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+   *
+   * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
+   * integration only builds once per registration cycle.
+   */
+  async registerEntrypoint(entrypointPath, registrationOptions) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
+    if (existingRegistration) {
+      return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
+    }
+    const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
+    this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
+    try {
+      return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
+    } catch (error) {
+      this.options.clearFailedRegistration?.(normalizedEntrypoint);
+      throw error;
+    } finally {
+      this.options.entrypointRegistrations.delete(normalizedEntrypoint);
+    }
+  }
+  async registerEntrypointInternal(entrypointPath, registrationOptions) {
+    if (this.options.watchedFiles.has(entrypointPath)) {
+      return this.options.watchedFiles.get(entrypointPath);
+    }
+    const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
+    this.options.watchedFiles.set(entrypointPath, outputUrl);
+    this.removeStaleEntrypointOutput(outputPath);
+    await registrationOptions.emit(entrypointPath, outputPath);
+    if (!fileSystem.exists(outputPath)) {
+      throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
+    }
+    return outputUrl;
+  }
+  async awaitEntrypointRegistration(registration, entrypointPath) {
+    if (process.env.NODE_ENV !== "development") {
+      return await registration;
+    }
+    return await Promise.race([
+      registration,
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
+        }, this.options.registrationTimeoutMs);
+      })
+    ]);
+  }
+  getEntrypointOutput(entrypointPath) {
+    const relativePath = path.relative(this.options.srcDir, entrypointPath);
+    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
+    const urlPath = encodedPathJs.split(path.sep).join("/");
+    return {
+      outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath)}`,
+      outputPath: path.join(this.options.distDir, urlPath)
+    };
+  }
+  removeStaleEntrypointOutput(outputPath) {
+    if (!fileSystem.exists(outputPath)) {
+      return;
+    }
+    try {
+      fileSystem.remove(outputPath);
+    } catch (error) {
+      appLogger.warn(
+        `[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  encodeDynamicSegments(filepath) {
+    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
+  }
+}
+export {
+  HmrEntrypointRegistrar
+};

package/src/adapters/shared/hmr-html-response.d.ts

@@ -0,0 +1,22 @@
+import type { IHmrManager } from '../../types/public-types.js';
+/**
+ * Returns whether a response is HTML and therefore eligible for development HMR
+ * runtime injection.
+ */
+export declare function isHtmlResponse(response: Response): boolean;
+/**
+ * Returns whether HTML responses should receive the HMR runtime bootstrap.
+ *
+ * This is shared because filesystem page responses and adapter-level HTML
+ * responses flow through different layers, but both need identical injection
+ * behavior in watch mode.
+ */
+export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean;
+/**
+ * Injects the development HMR runtime script into an HTML response if it is not
+ * already present.
+ *
+ * The check is intentionally idempotent because an HTML response can pass
+ * through more than one development-layer wrapper before reaching the client.
+ */
+export declare function injectHmrRuntimeIntoHtmlResponse(response: Response): Promise<Response>;

package/src/adapters/shared/hmr-html-response.js

@@ -0,0 +1,33 @@
+const HMR_RUNTIME_IMPORT = "import '/_hmr_runtime.js'";
+const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};<\/script>`;
+function isHtmlResponse(response) {
+  const contentType = response.headers.get("Content-Type");
+  return contentType !== null && contentType.startsWith("text/html");
+}
+function shouldInjectHmrHtmlResponse(watch, hmrManager) {
+  return watch && hmrManager?.isEnabled() === true;
+}
+async function injectHmrRuntimeIntoHtmlResponse(response) {
+  const html = await response.text();
+  const headers = new Headers(response.headers);
+  headers.set("Cache-Control", "no-store, must-revalidate");
+  headers.delete("Content-Length");
+  if (html.includes(HMR_RUNTIME_IMPORT)) {
+    return new Response(html, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  }
+  const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
+  return new Response(updatedHtml, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+export {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+};

package/src/adapters/shared/render-context.d.ts

@@ -1,7 +1,9 @@
-import type { RenderContext } from '../../public-types.js';
-import type { IntegrationPlugin } 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: IntegrationPlugin[];
+    integrations: AnyIntegrationPlugin[];
+    rendererModules?: unknown;
+    importServerModule?: (filePath: string) => Promise<unknown>;
 }
 /**
  * Creates a render context for route handlers.

package/src/adapters/shared/render-context.js

@@ -1,4 +1,8 @@
+import { fileURLToPath } from "node:url";
 import { invariant } from "../../utils/invariant.js";
+function resolveServerModulePath(filePath) {
+  return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
+}
 function mergePropsWithLocals(props, locals) {
   if (!locals || typeof props !== "object" || props === null) {
     return props;
@@ -15,12 +19,31 @@ function createRenderContext(options) {
     );
     const integration = integrations.find((i) => i.name === integrationName);
     invariant(!!integration, `No integration found for: ${integrationName}`);
-    return integration.initializeRenderer();
+    return integration.initializeRenderer({
+      rendererModules: options.rendererModules
+    });
   };
-  return {
+  const renderContext = {
+    importServerModule: async (filePath) => {
+      invariant(!!options.importServerModule, "Server module importing is not available in this render context.");
+      return await options.importServerModule(resolveServerModulePath(filePath));
+    },
+    async renderServerModule(filePath, props, renderOptions) {
+      const module = await renderContext.importServerModule(filePath);
+      const view = module.default;
+      const locals = this?.locals;
+      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+      const renderer = getRendererForView(view);
+      const ctx = {
+        partial: false,
+        status: renderOptions?.status,
+        headers: renderOptions?.headers
+      };
+      return await renderer.renderToResponse(view, mergedProps, ctx);
+    },
     async render(view, props, renderOptions) {
       const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props, locals);
+      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
       const renderer = getRendererForView(view);
       const ctx = {
         partial: false,
@@ -63,6 +86,7 @@ function createRenderContext(options) {
       });
     }
   };
+  return renderContext;
 }
 export {
   createRenderContext

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

@@ -0,0 +1,26 @@
+import type { ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type RuntimeBinding = {
+    preferredPort: number;
+    preferredHostname: string;
+    runtimeOrigin: string;
+    serveOptions: Record<string, unknown>;
+    watch: boolean;
+};
+export type StaticRuntimeMode = {
+    requiresFetchRuntime: boolean;
+    canBuildWithoutRuntimeServer: boolean;
+};
+export declare function resolveServeRuntimeOrigin(serveOptions: {
+    hostname?: string;
+    port?: number | string;
+}): string;
+export declare function resolveRuntimeBinding(options: {
+    cliArgs: ReturnParseCliArgs;
+    serverOptions?: Record<string, unknown>;
+    env?: NodeJS.ProcessEnv;
+}): RuntimeBinding;
+export declare function resolveStaticRuntimeMode(options: {
+    appConfig: EcoPagesAppConfig;
+    cliArgs: ReturnParseCliArgs;
+}): StaticRuntimeMode;

package/src/adapters/shared/runtime-app-bootstrap.js

@@ -0,0 +1,46 @@
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+function normalizeOriginHostname(hostname) {
+  if (hostname.includes(":") && !hostname.startsWith("[") && !hostname.endsWith("]")) {
+    return `[${hostname}]`;
+  }
+  return hostname;
+}
+function resolveServeRuntimeOrigin(serveOptions) {
+  const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
+  const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+  return `http://${hostname}:${port}`;
+}
+function resolveRuntimeBinding(options) {
+  const env = options.env ?? process.env;
+  const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : void 0) ?? DEFAULT_ECOPAGES_PORT;
+  const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
+  return {
+    preferredPort,
+    preferredHostname,
+    runtimeOrigin: resolveServeRuntimeOrigin({
+      hostname: preferredHostname,
+      port: preferredPort
+    }),
+    serveOptions: {
+      port: preferredPort,
+      hostname: preferredHostname,
+      ...options.serverOptions ?? {}
+    },
+    watch: options.cliArgs.dev
+  };
+}
+function resolveStaticRuntimeMode(options) {
+  const requiresFetchRuntime = options.appConfig.integrations.some(
+    (integration) => integration.staticBuildStep === "fetch"
+  );
+  const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
+  return {
+    requiresFetchRuntime,
+    canBuildWithoutRuntimeServer
+  };
+}
+export {
+  resolveRuntimeBinding,
+  resolveServeRuntimeOrigin,
+  resolveStaticRuntimeMode
+};

package/src/adapters/shared/runtime-host.d.ts

@@ -0,0 +1,12 @@
+export interface RuntimeHost<TServer, TServeOptions> {
+    start(options: RuntimeHostStartOptions<TServeOptions>): Promise<TServer>;
+    stop(server: TServer, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    getOrigin(server: TServer, fallbackServeOptions: TServeOptions): string;
+}
+export interface RuntimeHostStartOptions<TServeOptions> {
+    serveOptions: TServeOptions;
+    handleRequest(request: Request): Promise<Response>;
+    onError(error: Error): Promise<void> | void;
+}

package/src/adapters/shared/server-adapter.d.ts

@@ -1,30 +1,47 @@
 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 { FSRouter } from '../../router/fs-router.js';
-import { SchemaValidationService } from '../../services/schema-validation-service.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 { ServerRouteHandler } from './server-route-handler.js';
-import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext, StaticRoute } from '../../public-types.js';
+import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext, StaticRoute } from '../../types/public-types.js';
+type SharedRequestContext = {
+    apiHandlers: ApiHandler[];
+    errorHandler?: ErrorHandler;
+    serverInstance?: any;
+    hmrManager?: any;
+};
 export declare abstract class SharedServerAdapter<TOptions extends ServerAdapterOptions, TResult extends ServerAdapterResult> extends AbstractServerAdapter<TOptions, TResult> {
-    protected router: FSRouter;
+    protected router: RouteRegistry;
     protected fileSystemResponseMatcher: FileSystemResponseMatcher;
     protected routeRendererFactory: RouteRendererFactory;
     protected routeHandler: ServerRouteHandler;
     protected staticSiteGenerator: StaticSiteGenerator;
     protected staticBuilder: ServerStaticBuilder;
     protected readonly schemaValidator: SchemaValidationService;
+    protected initializeSharedRouteHandling(options: {
+        staticRoutes: StaticRoute[];
+        hmrManager?: any;
+    }): Promise<void>;
+    protected createSharedWatchRefreshCallback(options: {
+        staticRoutes: StaticRoute[];
+        hmrManager?: any;
+        onRoutesReady?: () => Promise<void> | void;
+        onError?: (error: Error) => Promise<void> | void;
+    }): () => Promise<void>;
     /**
-     * Scans the filesystem and dynamically constructs the universal router map.
+     * 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 `FSRouter` instance becomes the central nervous system for mapping WinterCG incoming
+     * The resulting `RouteRegistry` instance becomes the central nervous system for mapping WinterCG incoming
      * Web Requests (`Request`) to their corresponding internal execution paths.
      */
     protected initSharedRouter(): Promise<void>;
+    private createRouteRegistryPageModuleAdapter;
     /**
      * Sets up the unified rendering pipeline and response matching chain.
      *
@@ -40,6 +57,8 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
      * @param hmrManager - The runtime-specific Hot Module Replacement orchestrator (if watching).
      */
     protected configureSharedResponseHandlers(staticRoutes: StaticRoute[], hmrManager?: any): void;
+    private createSharedResponseHandlerDependencies;
+    private createSharedPageCacheService;
     protected getCacheService(): CacheInvalidator | null;
     protected getRenderContext(): RenderContext;
     /**
@@ -60,6 +79,10 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
      * @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;
@@ -67,6 +90,8 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
         routeConfig: ApiHandler;
         params: Record<string, string | string[]>;
     } | null;
+    private tryHandleSharedHmrRequest;
+    private tryHandleSharedApiRequest;
     /**
      * Universally processes an incoming WinterCG Web standard Request.
      *
@@ -78,10 +103,6 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
      * Both Bun and Node bindings fall back to this exact function once they have mapped their
      * native HTTP objects into Web Standard Requests.
      */
-    handleSharedRequest(request: Request, context: {
-        apiHandlers: ApiHandler[];
-        errorHandler?: ErrorHandler;
-        serverInstance?: any;
-        hmrManager?: any;
-    }): Promise<Response>;
+    handleSharedRequest(request: Request, context: SharedRequestContext): Promise<Response>;
 }
+export {};