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

package/src/adapters/shared/file-route-middleware-pipeline.js

@@ -1,98 +0,0 @@
-import { createRequire } from "../../utils/locals-utils.js";
-import { ApiResponseBuilder } from "./api-response.js";
-import { LocalsAccessError } from "../../errors/locals-access-error.js";
-const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
-  CTX_RENDER_UNAVAILABLE: "[ecopages] ctx.render is not available in file-route middleware",
-  CTX_RENDER_PARTIAL_UNAVAILABLE: "[ecopages] ctx.renderPartial is not available in file-route middleware",
-  middlewareRequiresDynamic: (filePath) => `[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`
-};
-class FileRouteMiddlewarePipeline {
-  constructor(cacheService) {
-    this.cacheService = cacheService;
-  }
-  /**
-   * Enforces the current middleware contract for file-routed pages.
-   *
-   * Middleware depends on request-scoped locals and therefore must not run when
-   * the page is treated as statically cacheable.
-   *
-   * @param input Middleware list, effective cache strategy, and page path.
-   * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
-   */
-  assertValidConfiguration(input) {
-    if (input.middleware.length > 0 && input.pageCacheStrategy !== "dynamic") {
-      throw new LocalsAccessError(
-        FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.middlewareRequiresDynamic(input.filePath)
-      );
-    }
-  }
-  /**
-   * Creates the request-scoped middleware context used by page middleware.
-   *
-   * The context intentionally disables `render()` and `renderPartial()` inside
-   * file-route middleware because rendering is owned by the page route pipeline,
-   * not by middleware stages.
-   *
-   * @param input Request details and the mutable locals store.
-   * @returns Middleware execution context.
-   */
-  createContext(input) {
-    const context = {
-      request: input.request,
-      params: input.params,
-      response: new ApiResponseBuilder(),
-      server: null,
-      services: {
-        cache: this.cacheService
-      },
-      locals: input.locals,
-      require: createRequire(() => context.locals),
-      render: async () => {
-        throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_UNAVAILABLE);
-      },
-      renderPartial: async () => {
-        throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_PARTIAL_UNAVAILABLE);
-      },
-      json: (data, options) => {
-        const builder = new ApiResponseBuilder();
-        if (options?.status) builder.status(options.status);
-        if (options?.headers) builder.headers(options.headers);
-        return builder.json(data);
-      },
-      html: (content, options) => {
-        const builder = new ApiResponseBuilder();
-        if (options?.status) builder.status(options.status);
-        if (options?.headers) builder.headers(options.headers);
-        return builder.html(content);
-      }
-    };
-    return context;
-  }
-  /**
-   * Runs the middleware chain and eventually delegates to the render callback.
-   *
-   * Middleware may short-circuit by returning a response directly. If the chain
-   * completes, the supplied `renderResponse` callback is executed exactly once.
-   *
-   * @param input Middleware context, chain, and terminal render callback.
-   * @returns Response from middleware or final render stage.
-   */
-  async run(input) {
-    if (input.middleware.length === 0) {
-      return input.renderResponse();
-    }
-    let index = 0;
-    const executeNext = async () => {
-      if (index < input.middleware.length) {
-        const current = input.middleware[index++];
-        return current(input.context, executeNext);
-      }
-      return input.renderResponse();
-    };
-    return executeNext();
-  }
-}
-export {
-  FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS,
-  FileRouteMiddlewarePipeline
-};

package/src/adapters/shared/fs-server-response-factory.d.ts

@@ -1,19 +0,0 @@
-import type { EcoPagesAppConfig, FileSystemServerOptions } from '../../internal-types.js';
-import type { RouteRendererBody } from '../../public-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-export declare class FileSystemServerResponseFactory {
-    private appConfig;
-    private routeRendererFactory;
-    private options;
-    constructor({ appConfig, routeRendererFactory, options, }: {
-        appConfig: EcoPagesAppConfig;
-        routeRendererFactory: RouteRendererFactory;
-        options: FileSystemServerOptions;
-    });
-    isHtml(contentType: string): contentType is "text/html";
-    shouldEnableGzip(contentType: string): boolean;
-    createResponseWithBody(body: RouteRendererBody, init?: ResponseInit): Promise<Response>;
-    createDefaultNotFoundResponse(): Promise<Response>;
-    createCustomNotFoundResponse(): Promise<Response>;
-    createFileResponse(filePath: string, contentType: string): Promise<Response>;
-}

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

@@ -1,97 +0,0 @@
-import { STATUS_MESSAGE } from "../../constants.js";
-import { appLogger } from "../../global/app-logger.js";
-import { fileSystem } from "@ecopages/file-system";
-class FileSystemServerResponseFactory {
-  appConfig;
-  routeRendererFactory;
-  options;
-  constructor({
-    appConfig,
-    routeRendererFactory,
-    options
-  }) {
-    this.appConfig = appConfig;
-    this.routeRendererFactory = routeRendererFactory;
-    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
-    });
-  }
-  async createCustomNotFoundResponse() {
-    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
-    try {
-      fileSystem.verifyFileExists(error404TemplatePath);
-    } catch {
-      appLogger.debug(
-        "Custom 404 template not found, falling back to default 404 response",
-        error404TemplatePath
-      );
-      return this.createDefaultNotFoundResponse();
-    }
-    const routeRenderer = this.routeRendererFactory.createRenderer(error404TemplatePath);
-    const result = await routeRenderer.createRoute({
-      file: error404TemplatePath
-    });
-    return await this.createResponseWithBody(result.body, {
-      status: 404,
-      statusText: STATUS_MESSAGE[404],
-      headers: {
-        "Content-Type": "text/html"
-      }
-    });
-  }
-  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 this.createCustomNotFoundResponse();
-    }
-  }
-}
-export {
-  FileSystemServerResponseFactory
-};

package/src/adapters/shared/fs-server-response-matcher.d.ts

@@ -1,71 +0,0 @@
-import type { MatchResult } from '../../internal-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-import type { FSRouter } from '../../router/fs-router.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 declare const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS: {
-    readonly transpilePageModuleFailed: (details: string) => string;
-    readonly noTranspiledOutputForPageModule: (filePath: string) => string;
-};
-export interface FileSystemResponseMatcherOptions {
-    router: FSRouter;
-    routeRendererFactory: RouteRendererFactory;
-    fileSystemResponseFactory: FileSystemServerResponseFactory;
-    /** Optional cache service. When null, caching is disabled. */
-    cacheService?: PageCacheService | null;
-    /** Default cache strategy when caching is enabled. @default 'static' */
-    defaultCacheStrategy?: CacheStrategy;
-}
-/**
- * Matches file-system routes to rendered HTML responses.
- *
- * This class sits at the request-time boundary between router matches and the
- * render pipeline. It coordinates page module inspection, request-local policy,
- * renderer invocation, middleware execution, cache integration, and fallback
- * error translation.
- */
-export declare class FileSystemResponseMatcher {
-    private router;
-    private routeRendererFactory;
-    private fileSystemResponseFactory;
-    private pageModuleImportService;
-    private pageRequestCacheCoordinator;
-    private fileRouteMiddlewarePipeline;
-    constructor({ router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
-    /**
-     * 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.
-     */
-    handleNoMatch(requestUrl: string): Promise<Response>;
-    /**
-     * 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.
-     */
-    handleMatch(match: MatchResult, request?: Request): Promise<Response>;
-    /**
-     * 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.
-     *
-     * @param filePath Absolute page module path.
-     * @returns Imported page module.
-     */
-    private importPageModule;
-    /**
-     * Get the underlying cache service for external invalidation.
-     */
-    getCacheService(): PageCacheService | null;
-}

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

@@ -1,155 +0,0 @@
-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 { 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 {
-  router;
-  routeRendererFactory;
-  fileSystemResponseFactory;
-  pageModuleImportService;
-  pageRequestCacheCoordinator;
-  fileRouteMiddlewarePipeline;
-  constructor({
-    router,
-    routeRendererFactory,
-    fileSystemResponseFactory,
-    cacheService = null,
-    defaultCacheStrategy = "static"
-  }) {
-    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();
-    }
-    const relativeUrl = requestUrl.startsWith("/") ? requestUrl.slice(1) : requestUrl;
-    const filePath = path.join(this.router.assetPrefix, relativeUrl);
-    const contentType = ServerUtils.getContentType(filePath);
-    return this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
-  }
-  /**
-   * 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) {
-    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;
-      this.fileRouteMiddlewarePipeline.assertValidConfiguration({
-        middleware: pageMiddleware,
-        pageCacheStrategy,
-        filePath: match.filePath
-      });
-      const routeRenderer = this.routeRendererFactory.createRenderer(match.filePath);
-      const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
-        request: resolvedRequest,
-        params: match.params,
-        locals: localsStore
-      });
-      const renderFn = async () => {
-        const result = await routeRenderer.createRoute({
-          file: match.filePath,
-          params: match.params,
-          query: match.query,
-          locals: localsForRender
-        });
-        const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
-        const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-        return { html, strategy };
-      };
-      const renderResponse = async () => {
-        return this.pageRequestCacheCoordinator.render({
-          cacheKey,
-          pageCacheStrategy,
-          renderFn
-        });
-      };
-      return await this.fileRouteMiddlewarePipeline.run({
-        middleware: pageMiddleware,
-        context: middlewareContext,
-        renderResponse
-      });
-    } catch (error) {
-      if (error instanceof Response) {
-        return error;
-      }
-      if (error instanceof LocalsAccessError) {
-        return new Response(error.message, {
-          status: 500,
-          headers: { "Content-Type": "text/plain; charset=utf-8" }
-        });
-      }
-      if (error instanceof Error) {
-        if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.pathname}`);
-        }
-      }
-      return this.fileSystemResponseFactory.createCustomNotFoundResponse();
-    }
-  }
-  /**
-   * 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.
-   *
-   * @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
-    });
-  }
-  /**
-   * Get the underlying cache service for external invalidation.
-   */
-  getCacheService() {
-    return this.pageRequestCacheCoordinator.getCacheService();
-  }
-}
-export {
-  FILE_SYSTEM_RESPONSE_MATCHER_ERRORS,
-  FileSystemResponseMatcher
-};

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

@@ -1,14 +0,0 @@
-import type { RenderContext } from '../../public-types.js';
-import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
-export interface CreateRenderContextOptions {
-    integrations: IntegrationPlugin[];
-}
-/**
- * Creates a render context for route handlers.
- * Provides render(), renderPartial(), json(), and html() methods that can be used
- * within route handlers to generate responses.
- *
- * @param options - Configuration options including available integrations
- * @returns A RenderContext object with methods for rendering views and creating responses
- */
-export declare function createRenderContext(options: CreateRenderContextOptions): RenderContext;

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

@@ -1,69 +0,0 @@
-import { invariant } from "../../utils/invariant.js";
-function mergePropsWithLocals(props, locals) {
-  if (!locals || typeof props !== "object" || props === null) {
-    return props;
-  }
-  return { ...props, locals };
-}
-function createRenderContext(options) {
-  const { integrations } = options;
-  const getRendererForView = (view) => {
-    const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
-    invariant(
-      !!integrationName,
-      "Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension."
-    );
-    const integration = integrations.find((i) => i.name === integrationName);
-    invariant(!!integration, `No integration found for: ${integrationName}`);
-    return integration.initializeRenderer();
-  };
-  return {
-    async render(view, props, renderOptions) {
-      const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props, locals);
-      const renderer = getRendererForView(view);
-      const ctx = {
-        partial: false,
-        status: renderOptions?.status,
-        headers: renderOptions?.headers
-      };
-      return renderer.renderToResponse(view, mergedProps, ctx);
-    },
-    async renderPartial(view, props, renderOptions) {
-      const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props, locals);
-      const renderer = getRendererForView(view);
-      const ctx = {
-        partial: true,
-        status: renderOptions?.status,
-        headers: renderOptions?.headers
-      };
-      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
-      });
-    },
-    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
-      });
-    }
-  };
-}
-export {
-  createRenderContext
-};

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

@@ -1,87 +0,0 @@
-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 { 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';
-export declare abstract class SharedServerAdapter<TOptions extends ServerAdapterOptions, TResult extends ServerAdapterResult> extends AbstractServerAdapter<TOptions, TResult> {
-    protected router: FSRouter;
-    protected fileSystemResponseMatcher: FileSystemResponseMatcher;
-    protected routeRendererFactory: RouteRendererFactory;
-    protected routeHandler: ServerRouteHandler;
-    protected staticSiteGenerator: StaticSiteGenerator;
-    protected staticBuilder: ServerStaticBuilder;
-    protected readonly schemaValidator: SchemaValidationService;
-    /**
-     * Scans the filesystem and dynamically constructs the universal router map.
-     *
-     * 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
-     * Web Requests (`Request`) to their corresponding internal execution paths.
-     */
-    protected initSharedRouter(): Promise<void>;
-    /**
-     * 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.
-     *
-     * 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 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 normalizePath;
-    private matchApiPath;
-    private getApiPathScore;
-    protected matchApiHandler(request: Request, apiHandlers: ApiHandler[]): {
-        routeConfig: ApiHandler;
-        params: Record<string, string | string[]>;
-    } | null;
-    /**
-     * 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.
-     * 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.
-     */
-    handleSharedRequest(request: Request, context: {
-        apiHandlers: ApiHandler[];
-        errorHandler?: ErrorHandler;
-        serverInstance?: any;
-        hmrManager?: any;
-    }): Promise<Response>;
-}