@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.8

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

@@ -0,0 +1,32 @@
+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();
+  if (html.includes(HMR_RUNTIME_IMPORT)) {
+    return new Response(html, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+  }
+  const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
+  const headers = new Headers(response.headers);
+  headers.delete("Content-Length");
+  return new Response(updatedHtml, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+export {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+};

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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,70 @@
+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();
+  };
+  const renderContext = {
+    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
+      });
+    }
+  };
+  return renderContext;
+}
+export {
+  createRenderContext
+};

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

@@ -0,0 +1,38 @@
+import { type BuildExecutor } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig, IClientBridge, IHmrManager } from '../../internal-types.js';
+/**
+ * Installs and returns the app-owned runtime build executor used by adapter
+ * startup and follow-up runtime work.
+ */
+export declare function installSharedRuntimeBuildExecutor(appConfig: EcoPagesAppConfig, options: {
+    development: boolean;
+}): BuildExecutor;
+/**
+ * Copies app public assets into dist and ensures the resolved assets directory
+ * exists before request handling begins.
+ */
+export declare function prepareSharedRuntimePublicDir(appConfig: EcoPagesAppConfig): void;
+/**
+ * Runs runtime plugin setup against app-owned config/runtime state and optional
+ * host plugin registration hooks.
+ */
+export declare function initializeSharedRuntimePlugins(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: unknown) => void;
+}): Promise<void>;
+/**
+ * Starts shared project watching for runtime adapters.
+ */
+export declare function startSharedProjectWatching(options: {
+    appConfig: EcoPagesAppConfig;
+    refreshRouterRoutesCallback: () => Promise<void>;
+    hmrManager: IHmrManager;
+    bridge: IClientBridge;
+}): Promise<void>;
+/**
+ * Binds a runtime HMR manager to app-owned plugin and integration state.
+ */
+export declare function bindSharedRuntimeHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): EcoBuildPlugin[];

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

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
+import { RESOLVED_ASSETS_DIR } from "../../constants.js";
+import { ProjectWatcher } from "../../watchers/project-watcher.js";
+function installSharedRuntimeBuildExecutor(appConfig, options) {
+  return installAppRuntimeBuildExecutor(appConfig, options);
+}
+function prepareSharedRuntimePublicDir(appConfig) {
+  const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+  if (fileSystem.exists(srcPublicDir)) {
+    fileSystem.copyDir(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+  }
+  fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+}
+async function initializeSharedRuntimePlugins(options) {
+  await setupAppRuntimePlugins(options);
+}
+async function startSharedProjectWatching(options) {
+  const watcher = new ProjectWatcher({
+    config: options.appConfig,
+    refreshRouterRoutesCallback: options.refreshRouterRoutesCallback,
+    hmrManager: options.hmrManager,
+    bridge: options.bridge
+  });
+  await watcher.createWatcherSubscription();
+}
+function bindSharedRuntimeHmrManager(appConfig, hmrManager) {
+  const browserBuildPlugins = getAppBrowserBuildPlugins(appConfig);
+  hmrManager.setPlugins(browserBuildPlugins);
+  for (const integration of appConfig.integrations) {
+    integration.setHmrManager(hmrManager);
+  }
+  return browserBuildPlugins;
+}
+export {
+  bindSharedRuntimeHmrManager,
+  initializeSharedRuntimePlugins,
+  installSharedRuntimeBuildExecutor,
+  prepareSharedRuntimePublicDir,
+  startSharedProjectWatching
+};

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

@@ -0,0 +1,97 @@
+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/server/fs-router.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';
+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;
+    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.
+     *
+     * 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>;
+}

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

@@ -0,0 +1,386 @@
+import path from "node:path";
+import { AbstractServerAdapter } from "../abstract/server-adapter.js";
+import { RouteRendererFactory } from "../../route-renderer/route-renderer.js";
+import { FSRouter } from "../../router/server/fs-router.js";
+import { FSRouterScanner } from "../../router/server/fs-router-scanner.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 "./explicit-static-route-matcher.js";
+import { FileSystemServerResponseFactory } from "./fs-server-response-factory.js";
+import { FileSystemResponseMatcher } from "./fs-server-response-matcher.js";
+import { ServerRouteHandler } from "./server-route-handler.js";
+import { createRenderContext } from "./render-context.js";
+import { createRequire } from "../../utils/locals-utils.js";
+import { HttpError } from "../../errors/http-error.js";
+import { ApiResponseBuilder } from "./api-response.js";
+import { appLogger } from "../../global/app-logger.js";
+import { fileSystem } from "@ecopages/file-system";
+class SharedServerAdapter extends AbstractServerAdapter {
+  router;
+  fileSystemResponseMatcher;
+  routeRendererFactory;
+  routeHandler;
+  staticSiteGenerator;
+  staticBuilder;
+  schemaValidator = new SchemaValidationService();
+  async initializeSharedRouteHandling(options) {
+    await this.initSharedRouter();
+    this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
+  }
+  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 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.
+   */
+  async initSharedRouter() {
+    const scanner = new FSRouterScanner({
+      dir: path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.pagesDir),
+      appConfig: this.appConfig,
+      origin: this.runtimeOrigin,
+      templatesExt: this.appConfig.templatesExt,
+      options: {
+        buildMode: !this.options?.watch
+      }
+    });
+    this.router = new FSRouter({
+      origin: this.runtimeOrigin,
+      assetPrefix: path.join(this.appConfig.rootDir, this.appConfig.distDir),
+      scanner
+    });
+    await this.router.init();
+  }
+  /**
+   * 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).
+   */
+  configureSharedResponseHandlers(staticRoutes, hmrManager) {
+    this.routeRendererFactory = new RouteRendererFactory({
+      appConfig: this.appConfig,
+      runtimeOrigin: this.runtimeOrigin
+    });
+    const fileSystemResponseFactory = new FileSystemServerResponseFactory({
+      appConfig: this.appConfig,
+      routeRendererFactory: this.routeRendererFactory,
+      options: {
+        watchMode: !!this.options?.watch
+      }
+    });
+    const cacheConfig = this.appConfig.cache;
+    const isCacheEnabled = cacheConfig?.enabled ?? !this.options?.watch;
+    let cacheService = null;
+    if (isCacheEnabled) {
+      const store = cacheConfig?.store === "memory" || !cacheConfig?.store ? new MemoryCacheStore({ maxEntries: cacheConfig?.maxEntries }) : cacheConfig.store;
+      cacheService = new PageCacheService({ store, enabled: true });
+    }
+    this.fileSystemResponseMatcher = new FileSystemResponseMatcher({
+      appConfig: this.appConfig,
+      router: this.router,
+      routeRendererFactory: this.routeRendererFactory,
+      fileSystemResponseFactory,
+      cacheService,
+      defaultCacheStrategy: cacheConfig?.defaultStrategy ?? "static"
+    });
+    const explicitStaticRouteMatcher = staticRoutes.length > 0 ? new ExplicitStaticRouteMatcher({
+      appConfig: this.appConfig,
+      routeRendererFactory: this.routeRendererFactory,
+      staticRoutes
+    }) : void 0;
+    this.routeHandler = new ServerRouteHandler({
+      router: this.router,
+      fileSystemResponseMatcher: this.fileSystemResponseMatcher,
+      explicitStaticRouteMatcher,
+      watch: !!this.options?.watch,
+      hmrManager
+    });
+  }
+  getCacheService() {
+    return this.fileSystemResponseMatcher?.getCacheService() ?? null;
+  }
+  getRenderContext() {
+    return createRenderContext({ integrations: this.appConfig.integrations });
+  }
+  /**
+   * 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.
+   */
+  async executeApiHandler(request, params, routeConfig, serverInstance, errorHandler) {
+    let context;
+    try {
+      const middleware = routeConfig.middleware || [];
+      const schema = routeConfig.schema;
+      const locals = {};
+      const normalizedParams = Object.fromEntries(
+        Object.entries(params).map(([key, value]) => [key, Array.isArray(value) ? value.join("/") : value])
+      );
+      context = {
+        request,
+        params: normalizedParams,
+        response: new ApiResponseBuilder(),
+        server: serverInstance,
+        locals,
+        require: createRequire(() => locals),
+        services: {
+          cache: this.getCacheService()
+        },
+        ...this.getRenderContext()
+      };
+      if (schema) {
+        const url = new URL(request.url);
+        const queryParams = Object.fromEntries(url.searchParams);
+        const headers = Object.fromEntries(request.headers);
+        let body;
+        if (schema.body) {
+          try {
+            const contentType = request.headers.get("Content-Type") || "";
+            if (contentType.includes("application/json")) body = await request.clone().json();
+            else if (contentType.includes("text/plain")) body = await request.clone().text();
+          } catch {
+            return context.response.status(400).json({ error: "Invalid request body" });
+          }
+        }
+        const validationResult = await this.schemaValidator.validateRequest(
+          { body, query: queryParams, headers, params: normalizedParams },
+          schema
+        );
+        if (!validationResult.success) {
+          return context.response.status(400).json({
+            error: "Validation failed",
+            issues: validationResult.errors
+          });
+        }
+        const validated = validationResult.data;
+        if (validated.body !== void 0) context.body = validated.body;
+        if (validated.query !== void 0) context.query = validated.query;
+        if (validated.headers !== void 0) context.headers = validated.headers;
+        if (validated.params !== void 0) context.params = validated.params;
+      }
+      if (middleware.length === 0) {
+        return await routeConfig.handler(context);
+      }
+      let index = 0;
+      const executeNext = async () => {
+        if (index < middleware.length) {
+          const currentMiddleware = middleware[index++];
+          return await currentMiddleware(context, executeNext);
+        }
+        return await routeConfig.handler(context);
+      };
+      return await executeNext();
+    } catch (error) {
+      if (error instanceof Response) return error;
+      if (errorHandler) {
+        try {
+          if (!context) {
+            const locals = {};
+            context = {
+              request,
+              params: Object.fromEntries(
+                Object.entries(params).map(([key, value]) => [
+                  key,
+                  Array.isArray(value) ? value.join("/") : value
+                ])
+              ),
+              response: new ApiResponseBuilder(),
+              server: serverInstance,
+              locals,
+              require: createRequire(() => locals),
+              services: { cache: this.getCacheService() },
+              ...this.getRenderContext()
+            };
+          }
+          return await errorHandler(error, context);
+        } catch (handlerError) {
+          appLogger.error(`[ecopages] Error in custom error handler: ${handlerError}`);
+        }
+      }
+      if (error instanceof HttpError) return error.toResponse();
+      appLogger.error(`[ecopages] Error handling API request: ${error}`);
+      return new Response("Internal Server Error", { status: 500 });
+    }
+  }
+  normalizePath(pathname) {
+    if (pathname.length > 1 && pathname.endsWith("/")) {
+      return pathname.slice(0, -1);
+    }
+    return pathname;
+  }
+  matchApiPath(pattern, pathname) {
+    const normalizedPattern = this.normalizePath(pattern);
+    const normalizedPathname = this.normalizePath(pathname);
+    const patternSegments = normalizedPattern.split("/").filter(Boolean);
+    const pathSegments = normalizedPathname.split("/").filter(Boolean);
+    const params = {};
+    let patternIndex = 0;
+    let pathIndex = 0;
+    while (patternIndex < patternSegments.length && pathIndex < pathSegments.length) {
+      const patternSegment = patternSegments[patternIndex];
+      const pathSegment = pathSegments[pathIndex];
+      if (patternSegment === "*") {
+        return params;
+      }
+      if (patternSegment.startsWith("[...") && patternSegment.endsWith("]")) {
+        const paramName = patternSegment.slice(4, -1);
+        params[paramName] = pathSegments.slice(pathIndex);
+        return params;
+      }
+      if (patternSegment.startsWith(":")) {
+        params[patternSegment.slice(1)] = pathSegment;
+        patternIndex++;
+        pathIndex++;
+        continue;
+      }
+      if (patternSegment.startsWith("[") && patternSegment.endsWith("]")) {
+        params[patternSegment.slice(1, -1)] = pathSegment;
+        patternIndex++;
+        pathIndex++;
+        continue;
+      }
+      if (patternSegment !== pathSegment) {
+        return null;
+      }
+      patternIndex++;
+      pathIndex++;
+    }
+    if (patternIndex < patternSegments.length) {
+      const remaining = patternSegments.slice(patternIndex);
+      const catchAll = remaining[0];
+      if (remaining.length === 1 && (catchAll === "*" || catchAll.startsWith("[...") && catchAll.endsWith("]"))) {
+        if (catchAll.startsWith("[...")) {
+          const paramName = catchAll.slice(4, -1);
+          params[paramName] = [];
+        }
+        return params;
+      }
+      return null;
+    }
+    if (pathIndex < pathSegments.length) {
+      return null;
+    }
+    return params;
+  }
+  getApiPathScore(pattern) {
+    const segments = this.normalizePath(pattern).split("/").filter(Boolean);
+    let score = 0;
+    for (const segment of segments) {
+      if (segment === "*" || segment.startsWith("[...") && segment.endsWith("]")) {
+        score += 10;
+      } else if (segment.startsWith(":") || segment.startsWith("[") && segment.endsWith("]")) {
+        score += 50;
+      } else {
+        score += 100;
+      }
+    }
+    return score;
+  }
+  matchApiHandler(request, apiHandlers) {
+    const pathname = new URL(request.url).pathname;
+    const method = request.method.toUpperCase();
+    const sortedHandlers = [...apiHandlers].sort((a, b) => {
+      return this.getApiPathScore(b.path) - this.getApiPathScore(a.path);
+    });
+    for (const routeConfig of sortedHandlers) {
+      const routeMethod = (routeConfig.method || "GET").toUpperCase();
+      if (routeMethod !== method) {
+        continue;
+      }
+      const params = this.matchApiPath(routeConfig.path, pathname);
+      if (params) {
+        return { routeConfig, params };
+      }
+    }
+    return 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.
+   */
+  async handleSharedRequest(request, context) {
+    const url = new URL(request.url);
+    if (url.pathname === "/_hmr_runtime.js" && context.hmrManager) {
+      const runtimePath = context.hmrManager.getRuntimePath();
+      if (fileSystem.exists(runtimePath)) {
+        return new Response(fileSystem.readFileAsBuffer(runtimePath), {
+          headers: { "Content-Type": "application/javascript" }
+        });
+      }
+    }
+    if (url.pathname.startsWith("/assets/_hmr/") && context.hmrManager) {
+      const relativePath = url.pathname.slice("/assets/_hmr/".length);
+      const assetPath = path.join(context.hmrManager.getDistDir(), relativePath);
+      if (fileSystem.exists(assetPath)) {
+        return new Response(fileSystem.readFileAsBuffer(assetPath), {
+          headers: { "Content-Type": "application/javascript" }
+        });
+      }
+    }
+    const apiMatch = this.matchApiHandler(request, context.apiHandlers);
+    if (apiMatch) {
+      return this.executeApiHandler(
+        request,
+        apiMatch.params,
+        apiMatch.routeConfig,
+        context.serverInstance,
+        context.errorHandler
+      );
+    }
+    return this.routeHandler.handleResponse(request);
+  }
+}
+export {
+  SharedServerAdapter
+};