@ecopages/core 0.2.0-alpha.25 → 0.2.0-alpha.26

package/src/adapters/node/static-content-server.js

@@ -0,0 +1,194 @@
+import { createServer } from "node:http";
+import { extname, join, normalize, sep } from "node:path";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from "../../config/constants.js";
+import { fileSystem } from "@ecopages/file-system";
+import { ServerUtils } from "../../utils/server-utils.module.js";
+class NodeStaticContentServer {
+  appConfig;
+  options;
+  server = null;
+  /**
+   * Creates the Node static-content server for one built app output directory.
+   */
+  constructor({ appConfig, options }) {
+    this.appConfig = appConfig;
+    this.options = {
+      hostname: options?.hostname ?? DEFAULT_ECOPAGES_HOSTNAME,
+      port: options?.port ?? DEFAULT_ECOPAGES_PORT
+    };
+  }
+  /**
+   * Returns whether the given content type should be served from a pre-gzipped
+   * companion file when available.
+   */
+  shouldServeGzip(contentType) {
+    return ["text/javascript", "text/css"].includes(contentType);
+  }
+  /**
+   * Normalizes a request pathname and rejects directory traversal attempts.
+   */
+  sanitizePath(pathname) {
+    const withoutLeadingSlash = pathname.replace(/^\/+/, "");
+    const normalizedPath = normalize(withoutLeadingSlash);
+    if (normalizedPath.startsWith("..") || normalizedPath.includes(`..${sep}`)) {
+      return null;
+    }
+    return normalizedPath;
+  }
+  /**
+   * Writes one HTTP response with the provided headers and optional body.
+   */
+  sendResponse(res, status, headers, body) {
+    res.statusCode = status;
+    for (const [key, value] of Object.entries(headers)) {
+      res.setHeader(key, value);
+    }
+    if (!body) {
+      res.end();
+      return;
+    }
+    res.end(body);
+  }
+  /**
+   * Serves the generated 404 page when present, or a plain-text fallback.
+   */
+  sendNotFoundPage(req, res) {
+    const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, "404.html");
+    const isHead = (req.method ?? "GET").toUpperCase() === "HEAD";
+    if (!fileSystem.exists(error404TemplatePath)) {
+      this.sendResponse(
+        res,
+        404,
+        { "Content-Type": "text/plain" },
+        isHead ? void 0 : Buffer.from(STATUS_MESSAGE[404])
+      );
+      return;
+    }
+    const file = fileSystem.readFileAsBuffer(error404TemplatePath);
+    this.sendResponse(res, 404, { "Content-Type": "text/html" }, isHead ? void 0 : file);
+  }
+  /**
+   * Serves one concrete file path, honoring gzip and HEAD semantics.
+   */
+  serveFile(req, res, filePath, status = 200) {
+    const contentType = ServerUtils.getContentType(extname(filePath));
+    const acceptsGzip = req.headers["accept-encoding"]?.includes("gzip");
+    const isHead = (req.method ?? "GET").toUpperCase() === "HEAD";
+    if (acceptsGzip && this.shouldServeGzip(contentType)) {
+      const gzipPath = `${filePath}.gz`;
+      if (fileSystem.exists(gzipPath)) {
+        const file2 = fileSystem.readFileAsBuffer(gzipPath);
+        this.sendResponse(
+          res,
+          status,
+          {
+            "Content-Type": contentType,
+            "Content-Encoding": "gzip",
+            Vary: "Accept-Encoding"
+          },
+          isHead ? void 0 : file2
+        );
+        return;
+      }
+    }
+    if (!fileSystem.exists(filePath)) {
+      this.sendNotFoundPage(req, res);
+      return;
+    }
+    const file = fileSystem.readFileAsBuffer(filePath);
+    this.sendResponse(res, status, { "Content-Type": contentType }, isHead ? void 0 : file);
+  }
+  /**
+   * Handles one incoming Node HTTP request against the built static output tree.
+   */
+  handleRequest(req, res) {
+    const method = (req.method ?? "GET").toUpperCase();
+    const isHead = method === "HEAD";
+    if (method !== "GET" && method !== "HEAD") {
+      this.sendResponse(
+        res,
+        405,
+        { Allow: "GET, HEAD", "Content-Type": "text/plain" },
+        isHead ? void 0 : Buffer.from("Method Not Allowed")
+      );
+      return;
+    }
+    const url = new URL(req.url ?? "/", "http://localhost");
+    let decodedPathname = "/";
+    try {
+      decodedPathname = decodeURIComponent(url.pathname);
+    } catch {
+      this.sendResponse(
+        res,
+        400,
+        { "Content-Type": "text/plain" },
+        isHead ? void 0 : Buffer.from("Invalid path")
+      );
+      return;
+    }
+    const pathname = decodedPathname === "/" ? "/index.html" : decodedPathname;
+    const relativePath = this.sanitizePath(pathname);
+    if (!relativePath) {
+      this.sendResponse(
+        res,
+        400,
+        { "Content-Type": "text/plain" },
+        isHead ? void 0 : Buffer.from("Invalid path")
+      );
+      return;
+    }
+    const basePath = join(this.appConfig.absolutePaths.distDir, relativePath);
+    if (pathname.includes(".")) {
+      this.serveFile(req, res, basePath);
+      return;
+    }
+    const htmlCandidates = [`${basePath}.html`, join(basePath, "index.html")];
+    for (const candidate of htmlCandidates) {
+      if (fileSystem.exists(candidate)) {
+        this.serveFile(req, res, candidate);
+        return;
+      }
+    }
+    this.sendNotFoundPage(req, res);
+  }
+  /**
+   * Starts the static preview server.
+   */
+  async start() {
+    if (this.server) {
+      return this.server;
+    }
+    this.server = createServer(this.handleRequest.bind(this));
+    const hostname = this.options.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+    const port = this.options.port ?? DEFAULT_ECOPAGES_PORT;
+    await new Promise((resolve) => {
+      this.server.listen(port, hostname, () => resolve());
+    });
+    return this.server;
+  }
+  /**
+   * Stops the static preview server and optionally closes active connections.
+   */
+  async stop(force = true) {
+    if (!this.server) {
+      return;
+    }
+    const activeServer = this.server;
+    this.server = null;
+    await new Promise((resolve, reject) => {
+      activeServer.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+      if (force) {
+        activeServer.closeAllConnections();
+      }
+    });
+  }
+}
+export {
+  NodeStaticContentServer
+};

package/src/adapters/shared/api-response.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A builder class for creating Response objects fluently.
+ */
+export declare class ApiResponseBuilder {
+    private _status;
+    private _headers;
+    /**
+     * Sets the HTTP status code for the response.
+     * @param code - The HTTP status code.
+     * @returns The builder instance for chaining.
+     */
+    status(code: Response['status']): this;
+    /**
+     * Adds or merges headers for the response.
+     * @param headersInit - Headers to add or merge.
+     * @returns The builder instance for chaining.
+     */
+    headers(headersInit: HeadersInit): this;
+    /**
+     * Creates a JSON response using the configured status and headers.
+     * @param data - The data to serialize.
+     * @returns A Response object.
+     */
+    json(data: any): Response;
+    /**
+     * Creates a plain text response using the configured status and headers.
+     * @param data - The text content.
+     * @returns A Response object.
+     */
+    text(data: string): Response;
+    /**
+     * Creates an HTML response using the configured status and headers.
+     * @param data - The HTML content.
+     * @returns A Response object.
+     */
+    html(data: string): Response;
+    /**
+     * Creates a redirect response.
+     * @param url - The URL to redirect to.
+     * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 302 if not set via status().
+     * @returns A Response object.
+     */
+    redirect(url: string, explicitStatus?: Response['status']): Response;
+    /**
+     * Creates an error response using the configured status and headers.
+     * If data is an object, it's treated as JSON, otherwise as text.
+     * @param data - The error data (string or object).
+     * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 500 if not set via status().
+     * @returns A Response object.
+     */
+    error(data: string | object, explicitStatus?: Response['status']): Response;
+}

package/src/adapters/shared/api-response.js

@@ -0,0 +1,96 @@
+class ApiResponseBuilder {
+  _status = 200;
+  _headers = new Headers();
+  /**
+   * Sets the HTTP status code for the response.
+   * @param code - The HTTP status code.
+   * @returns The builder instance for chaining.
+   */
+  status(code) {
+    this._status = code;
+    return this;
+  }
+  /**
+   * Adds or merges headers for the response.
+   * @param headersInit - Headers to add or merge.
+   * @returns The builder instance for chaining.
+   */
+  headers(headersInit) {
+    const inputHeaders = new Headers(headersInit);
+    inputHeaders.forEach((value, key) => {
+      this._headers.set(key, value);
+    });
+    return this;
+  }
+  /**
+   * Creates a JSON response using the configured status and headers.
+   * @param data - The data to serialize.
+   * @returns A Response object.
+   */
+  json(data) {
+    if (!this._headers.has("Content-Type")) {
+      this._headers.set("Content-Type", "application/json; charset=utf-8");
+    }
+    return new Response(JSON.stringify(data), { status: this._status, headers: this._headers });
+  }
+  /**
+   * Creates a plain text response using the configured status and headers.
+   * @param data - The text content.
+   * @returns A Response object.
+   */
+  text(data) {
+    if (!this._headers.has("Content-Type")) {
+      this._headers.set("Content-Type", "text/plain; charset=utf-8");
+    }
+    return new Response(data, { status: this._status, headers: this._headers });
+  }
+  /**
+   * Creates an HTML response using the configured status and headers.
+   * @param data - The HTML content.
+   * @returns A Response object.
+   */
+  html(data) {
+    if (!this._headers.has("Content-Type")) {
+      this._headers.set("Content-Type", "text/html; charset=utf-8");
+    }
+    return new Response(data, { status: this._status, headers: this._headers });
+  }
+  /**
+   * Creates a redirect response.
+   * @param url - The URL to redirect to.
+   * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 302 if not set via status().
+   * @returns A Response object.
+   */
+  redirect(url, explicitStatus) {
+    const redirectStatus = explicitStatus ?? (this._status === 200 ? 302 : this._status);
+    this._headers.set("Location", url);
+    return new Response(null, { status: redirectStatus, headers: this._headers });
+  }
+  /**
+   * Creates an error response using the configured status and headers.
+   * If data is an object, it's treated as JSON, otherwise as text.
+   * @param data - The error data (string or object).
+   * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 500 if not set via status().
+   * @returns A Response object.
+   */
+  error(data, explicitStatus) {
+    const errorStatus = explicitStatus ?? (this._status === 200 ? 500 : this._status);
+    this.status(errorStatus);
+    if (typeof data === "object" && data !== null) {
+      if (!this._headers.has("Content-Type")) {
+        this._headers.set("Content-Type", "application/json; charset=utf-8");
+      }
+      return new Response(JSON.stringify({ error: data }), {
+        status: this._status,
+        headers: this._headers
+      });
+    }
+    if (!this._headers.has("Content-Type")) {
+      this._headers.set("Content-Type", "text/plain; charset=utf-8");
+    }
+    return new Response(String(data), { status: this._status, headers: this._headers });
+  }
+}
+export {
+  ApiResponseBuilder
+};

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

@@ -0,0 +1,18 @@
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../types/public-types.js';
+import { AbstractApplicationAdapter, type ApplicationAdapterOptions, type RouteGroupDefinition, type RouteHandler } from '../abstract/application-adapter.js';
+export declare abstract class SharedApplicationAdapter<TOptions extends ApplicationAdapterOptions = ApplicationAdapterOptions, TServer = any, TRequest extends Request = Request> extends AbstractApplicationAdapter<TOptions, TServer, TRequest> {
+    protected register<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, method: ApiHandler['method'], handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
+    get<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
+    post<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
+    put<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
+    delete<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
+    patch<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
+    options<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
+    head<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
+    route<P extends string>(path: P, method: ApiHandler['method'], handler: RouteHandler<TRequest, TServer>, options?: RouteOptions<TRequest, TServer>): this;
+    add(handler: ApiHandler<string, TRequest, TServer>): this;
+    group<TMiddleware extends readonly Middleware<TRequest, TServer, any>[] = []>(prefixOrGroup: string | RouteGroupDefinition<TRequest, TServer>, callback?: (builder: TMiddleware extends readonly Middleware<TRequest, TServer, infer TContext>[] ? RouteGroupBuilder<TRequest, TServer, TContext> : RouteGroupBuilder<TRequest, TServer>) => void, options?: {
+        middleware?: TMiddleware;
+    }): this;
+    private registerGroup;
+}

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

@@ -0,0 +1,90 @@
+import {
+  AbstractApplicationAdapter
+} from "../abstract/application-adapter.js";
+class SharedApplicationAdapter extends AbstractApplicationAdapter {
+  register(path, method, handler, options) {
+    return this.addRouteHandler(path, method, handler, options?.middleware, options?.schema);
+  }
+  get(path, handler, options) {
+    return this.register(path, "GET", handler, options);
+  }
+  post(path, handler, options) {
+    return this.register(path, "POST", handler, options);
+  }
+  put(path, handler, options) {
+    return this.register(path, "PUT", handler, options);
+  }
+  delete(path, handler, options) {
+    return this.register(path, "DELETE", handler, options);
+  }
+  patch(path, handler, options) {
+    return this.register(path, "PATCH", handler, options);
+  }
+  options(path, handler, options) {
+    return this.register(path, "OPTIONS", handler, options);
+  }
+  head(path, handler, options) {
+    return this.register(path, "HEAD", handler, options);
+  }
+  route(path, method, handler, options) {
+    return this.register(path, method, handler, options);
+  }
+  add(handler) {
+    return this.addRouteHandler(handler.path, handler.method, handler.handler, handler.middleware, handler.schema);
+  }
+  group(prefixOrGroup, callback, options) {
+    if (typeof prefixOrGroup === "object") {
+      return this.registerGroup(prefixOrGroup);
+    }
+    const normalizedPrefix = prefixOrGroup.endsWith("/") ? prefixOrGroup.slice(0, -1) : prefixOrGroup;
+    const groupMiddleware = options?.middleware ?? [];
+    const createHandler = (method) => {
+      return ((path, handler, routeOptions) => {
+        const combinedMiddleware = [
+          ...groupMiddleware,
+          ...routeOptions?.middleware ?? []
+        ];
+        const fullPath = path === "/" ? normalizedPrefix : `${normalizedPrefix}${path}`;
+        this.addRouteHandler(
+          fullPath,
+          method,
+          handler,
+          combinedMiddleware.length > 0 ? combinedMiddleware : void 0,
+          routeOptions?.schema
+        );
+        return builder;
+      });
+    };
+    const builder = {
+      get: createHandler("GET"),
+      post: createHandler("POST"),
+      put: createHandler("PUT"),
+      delete: createHandler("DELETE"),
+      patch: createHandler("PATCH"),
+      options: createHandler("OPTIONS"),
+      head: createHandler("HEAD")
+    };
+    callback?.(builder);
+    return this;
+  }
+  registerGroup(group) {
+    const normalizedPrefix = group.prefix.endsWith("/") ? group.prefix.slice(0, -1) : group.prefix;
+    const groupMiddleware = group.middleware ?? [];
+    for (const route of group.routes) {
+      const normalizedPath = route.path.startsWith("/") ? route.path : `/${route.path}`;
+      const fullPath = route.path === "/" ? normalizedPrefix : `${normalizedPrefix}${normalizedPath}`;
+      const combinedMiddleware = [...groupMiddleware, ...route.middleware ?? []];
+      this.addRouteHandler(
+        fullPath,
+        route.method,
+        route.handler,
+        combinedMiddleware.length > 0 ? combinedMiddleware : void 0,
+        route.schema
+      );
+    }
+    return this;
+  }
+}
+export {
+  SharedApplicationAdapter
+};

package/src/adapters/shared/define-api-handler.d.ts

@@ -0,0 +1,25 @@
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteSchema, TypedGroupHandlerContext } from '../../types/public-types.js';
+type UniversalContext = ApiHandlerContext<Request, unknown>;
+type SchemaHandlerContext<TSchema extends RouteSchema | undefined, TContext extends UniversalContext> = TSchema extends RouteSchema ? TypedGroupHandlerContext<TSchema, TContext> : TContext;
+export declare function defineApiHandler<TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[];
+    schema?: TSchema;
+}): ApiHandler<TPath, Request, unknown>;
+export interface GroupHandler<TPrefix extends string = string> {
+    prefix: TPrefix;
+    middleware?: readonly Middleware<Request, unknown, any>[];
+    routes: readonly ApiHandler<string, Request, unknown>[];
+}
+type GroupDefineHandler<TContext extends UniversalContext> = <const TPath extends string, TSchema extends RouteSchema | undefined = undefined>(handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {
+    path: TPath;
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[];
+    schema?: TSchema;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare function defineGroupHandler<TPrefix extends string, TMiddleware extends readonly Middleware<Request, unknown, any>[] = [], TContext extends UniversalContext = TMiddleware extends readonly Middleware<Request, unknown, infer TGroupContext>[] ? TGroupContext : UniversalContext>(config: {
+    prefix: TPrefix;
+    middleware?: TMiddleware;
+    routes: (define: GroupDefineHandler<TContext>) => readonly ApiHandler<string, Request, unknown>[];
+}): GroupHandler<TPrefix>;
+export {};

package/src/adapters/shared/define-api-handler.js

@@ -0,0 +1,15 @@
+function defineApiHandler(handler) {
+  return handler;
+}
+function defineGroupHandler(config) {
+  const define = ((handler) => handler);
+  return {
+    prefix: config.prefix,
+    middleware: config.middleware,
+    routes: config.routes(define)
+  };
+}
+export {
+  defineApiHandler,
+  defineGroupHandler
+};

package/src/adapters/shared/explicit-static-route-matcher.d.ts

@@ -0,0 +1,38 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { StaticRoute } from '../../types/public-types.js';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+export declare const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS: {
+    readonly missingIntegration: (routePath: string) => string;
+    readonly noRendererForIntegration: (integrationName: string) => string;
+};
+export interface ExplicitStaticRouteMatcherOptions {
+    appConfig: EcoPagesAppConfig;
+    routeRendererFactory: RouteRendererFactory;
+    staticRoutes: StaticRoute[];
+}
+export interface ExplicitRouteMatch {
+    route: StaticRoute;
+    params: Record<string, string>;
+}
+export declare class ExplicitStaticRouteMatcher {
+    private readonly appConfig;
+    private readonly routeRendererFactory;
+    private readonly staticRoutes;
+    constructor({ appConfig, routeRendererFactory, staticRoutes }: ExplicitStaticRouteMatcherOptions);
+    /**
+     * Match a request URL against explicit static routes.
+     * Returns the matched route and extracted params, or null if no match.
+     */
+    match(url: string): ExplicitRouteMatch | null;
+    /**
+     * Match a route pattern against a pathname.
+     * Supports :param and [param] syntax.
+     * Returns extracted params or null if no match.
+     */
+    private matchRoute;
+    /**
+     * Handle a matched explicit static route.
+     * Resolves the loader and renders the view using the appropriate integration renderer.
+     */
+    handleMatch(match: ExplicitRouteMatch): Promise<Response>;
+}

package/src/adapters/shared/explicit-static-route-matcher.js

@@ -0,0 +1,103 @@
+import { appLogger } from "../../global/app-logger.js";
+const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
+  missingIntegration: (routePath) => `View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page() and exported as default.`,
+  noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`
+};
+function getViewIntegrationName(view) {
+  return view.config?.integration ?? view.config?.__eco?.integration;
+}
+class ExplicitStaticRouteMatcher {
+  appConfig;
+  routeRendererFactory;
+  staticRoutes;
+  constructor({ appConfig, routeRendererFactory, staticRoutes }) {
+    this.appConfig = appConfig;
+    this.routeRendererFactory = routeRendererFactory;
+    this.staticRoutes = staticRoutes;
+  }
+  /**
+   * Match a request URL against explicit static routes.
+   * Returns the matched route and extracted params, or null if no match.
+   */
+  match(url) {
+    const pathname = new URL(url).pathname;
+    for (const route of this.staticRoutes) {
+      const params = this.matchRoute(route.path, pathname);
+      if (params !== null) {
+        return { route, params };
+      }
+    }
+    return null;
+  }
+  /**
+   * Match a route pattern against a pathname.
+   * Supports :param and [param] syntax.
+   * Returns extracted params or null if no match.
+   */
+  matchRoute(pattern, pathname) {
+    const patternSegments = pattern.split("/").filter(Boolean);
+    const pathSegments = pathname.split("/").filter(Boolean);
+    if (patternSegments.length !== pathSegments.length) {
+      const lastPattern = patternSegments[patternSegments.length - 1];
+      const isCatchAll = lastPattern?.startsWith("[...") || lastPattern?.startsWith(":...");
+      if (!isCatchAll) {
+        return null;
+      }
+    }
+    const params = {};
+    for (let i = 0; i < patternSegments.length; i++) {
+      const patternPart = patternSegments[i];
+      const pathPart = pathSegments[i];
+      if (patternPart.startsWith(":...") || patternPart.startsWith("[...")) {
+        const paramName = patternPart.replace(/^(:\.\.\.|\[\.\.\.)/, "").replace(/\]$/, "");
+        params[paramName] = pathSegments.slice(i).join("/");
+        return params;
+      }
+      if (patternPart.startsWith(":")) {
+        const paramName = patternPart.slice(1);
+        params[paramName] = pathPart;
+      } else if (patternPart.startsWith("[") && patternPart.endsWith("]")) {
+        const paramName = patternPart.slice(1, -1);
+        params[paramName] = pathPart;
+      } else if (patternPart !== pathPart) {
+        return null;
+      }
+    }
+    return params;
+  }
+  /**
+   * Handle a matched explicit static route.
+   * Resolves the loader and renders the view using the appropriate integration renderer.
+   */
+  async handleMatch(match) {
+    const { route, params } = match;
+    try {
+      const mod = await route.loader();
+      const view = mod.default;
+      const integrationName = getViewIntegrationName(view);
+      if (!integrationName) {
+        throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.missingIntegration(route.path));
+      }
+      const renderer = this.routeRendererFactory.getRendererByIntegration(integrationName);
+      if (!renderer) {
+        throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.noRendererForIntegration(integrationName));
+      }
+      const props = view.staticProps ? (await view.staticProps({
+        pathname: { params },
+        appConfig: this.appConfig,
+        runtimeOrigin: this.appConfig.baseUrl
+      })).props : {};
+      return renderer.renderToResponse(view, props, {});
+    } catch (error) {
+      appLogger.error(
+        `Error rendering explicit static route ${route.path}:`,
+        error instanceof Error ? error : String(error)
+      );
+      throw error;
+    }
+  }
+}
+export {
+  EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS,
+  ExplicitStaticRouteMatcher
+};