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

package/src/adapters/shared/http/api-request-pipeline.js

@@ -0,0 +1,129 @@
+import { createRequire } from "../../../utils/locals-utils.js";
+import { HttpError } from "../../../errors/http-error.js";
+import { ApiResponseBuilder } from "./api-response.js";
+import { runMiddlewareChain } from "./run-middleware-chain.js";
+import { matchApiPathPattern, scoreApiPathPattern } from "../../abstract/segment-path-matcher.js";
+import { appLogger } from "../../../global/app-logger.js";
+class ApiRequestPipeline {
+  schemaValidator;
+  getRenderContext;
+  getCacheService;
+  constructor(options) {
+    this.schemaValidator = options.schemaValidator;
+    this.getRenderContext = options.getRenderContext;
+    this.getCacheService = options.getCacheService;
+  }
+  match(request, apiHandlers) {
+    const pathname = new URL(request.url).pathname;
+    const method = request.method.toUpperCase();
+    const sortedHandlers = [...apiHandlers].sort((a, b) => {
+      return scoreApiPathPattern(b.path) - scoreApiPathPattern(a.path);
+    });
+    for (const routeConfig of sortedHandlers) {
+      const routeMethod = (routeConfig.method || "GET").toUpperCase();
+      if (routeMethod !== method) {
+        continue;
+      }
+      const params = matchApiPathPattern(routeConfig.path, pathname);
+      if (params) {
+        return { routeConfig, params };
+      }
+    }
+    return null;
+  }
+  async tryHandle(request, apiHandlers, serverInstance, errorHandler) {
+    const apiMatch = this.match(request, apiHandlers);
+    if (!apiMatch) {
+      return null;
+    }
+    return await this.execute(request, apiMatch.params, apiMatch.routeConfig, serverInstance, errorHandler);
+  }
+  async execute(request, params, routeConfig, serverInstance, errorHandler) {
+    let context;
+    try {
+      context = this.createContext(request, params, serverInstance);
+      const schemaResponse = await this.applyRequestSchema(context, routeConfig.schema);
+      if (schemaResponse) {
+        return schemaResponse;
+      }
+      return await this.runMiddlewareChain(context, routeConfig);
+    } catch (error) {
+      if (error instanceof Response) return error;
+      if (errorHandler) {
+        try {
+          if (!context) {
+            context = this.createContext(request, params, serverInstance);
+          }
+          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 });
+    }
+  }
+  createContext(request, params, serverInstance) {
+    const locals = {};
+    const normalizedParams = this.normalizeParams(params);
+    return {
+      request,
+      params: normalizedParams,
+      response: new ApiResponseBuilder(),
+      server: serverInstance,
+      locals,
+      require: createRequire(() => locals),
+      services: {
+        cache: this.getCacheService()
+      },
+      ...this.getRenderContext()
+    };
+  }
+  normalizeParams(params) {
+    return Object.fromEntries(
+      Object.entries(params).map(([key, value]) => [key, Array.isArray(value) ? value.join("/") : value])
+    );
+  }
+  async applyRequestSchema(context, schema) {
+    if (!schema) {
+      return void 0;
+    }
+    const url = new URL(context.request.url);
+    const queryParams = Object.fromEntries(url.searchParams);
+    const headers = Object.fromEntries(context.request.headers);
+    let body;
+    if (schema.body) {
+      try {
+        const contentType = context.request.headers.get("Content-Type") || "";
+        if (contentType.includes("application/json")) body = await context.request.clone().json();
+        else if (contentType.includes("text/plain")) body = await context.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: context.params },
+      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;
+    return void 0;
+  }
+  async runMiddlewareChain(context, routeConfig) {
+    const middleware = routeConfig.middleware ?? [];
+    return runMiddlewareChain(middleware, context, async () => await routeConfig.handler(context));
+  }
+}
+export {
+  ApiRequestPipeline
+};

package/src/adapters/shared/{api-response.d.ts → http/api-response.d.ts}

@@ -21,7 +21,7 @@ export declare class ApiResponseBuilder {
      * @param data - The data to serialize.
      * @returns A Response object.
      */
-    json(data: any): Response;
+    json(data: unknown): Response;
     /**
      * Creates a plain text response using the configured status and headers.
      * @param data - The text content.

package/src/adapters/shared/{api-response.js → http/api-response.js}

@@ -1,3 +1,4 @@
+import { createBodyResponse } from "./create-body-response.js";
 class ApiResponseBuilder {
   _status = 200;
   _headers = new Headers();
@@ -28,10 +29,7 @@ class ApiResponseBuilder {
    * @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 });
+    return createBodyResponse("json", data, { status: this._status, headers: this._headers });
   }
   /**
    * Creates a plain text response using the configured status and headers.
@@ -39,10 +37,7 @@ class ApiResponseBuilder {
    * @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 });
+    return createBodyResponse("text", data, { status: this._status, headers: this._headers });
   }
   /**
    * Creates an HTML response using the configured status and headers.
@@ -50,10 +45,7 @@ class ApiResponseBuilder {
    * @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 });
+    return createBodyResponse("html", data, { status: this._status, headers: this._headers });
   }
   /**
    * Creates a redirect response.
@@ -77,18 +69,9 @@ class ApiResponseBuilder {
     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 createBodyResponse("json", { error: data }, { status: this._status, headers: this._headers });
     }
-    return new Response(String(data), { status: this._status, headers: this._headers });
+    return createBodyResponse("text", String(data), { status: this._status, headers: this._headers });
   }
 }
 export {

package/src/adapters/shared/http/create-body-response.d.ts

@@ -0,0 +1,12 @@
+export type BodyResponseKind = 'json' | 'html' | 'text';
+export type CreateBodyResponseInit = {
+    status?: Response['status'];
+    headers?: HeadersInit;
+};
+/**
+ * Builds a typed HTTP response body for JSON, HTML, or plain text.
+ *
+ * @remarks
+ * Sole internal emission path for adapter response helpers. Not exported from `@ecopages/core`.
+ */
+export declare function createBodyResponse(kind: BodyResponseKind, data: unknown, init?: CreateBodyResponseInit): Response;

package/src/adapters/shared/http/create-body-response.js

@@ -0,0 +1,23 @@
+function createBodyResponse(kind, data, init) {
+  const headers = new Headers(init?.headers);
+  const status = init?.status ?? 200;
+  if (kind === "json") {
+    if (!headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json; charset=utf-8");
+    }
+    return new Response(JSON.stringify(data), { status, headers });
+  }
+  if (kind === "html") {
+    if (!headers.has("Content-Type")) {
+      headers.set("Content-Type", "text/html; charset=utf-8");
+    }
+    return new Response(String(data), { status, headers });
+  }
+  if (!headers.has("Content-Type")) {
+    headers.set("Content-Type", "text/plain; charset=utf-8");
+  }
+  return new Response(String(data), { status, headers });
+}
+export {
+  createBodyResponse
+};

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

@@ -0,0 +1,90 @@
+import type { ApiHandler, ApiHandlerContext, Middleware, ResponseOptions, 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;
+type DefineApiHandlerInput<TPath extends string, TSchema extends RouteSchema | undefined, TContext extends UniversalContext> = Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema' | 'method'> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[];
+    schema?: TSchema;
+};
+export declare function defineApiHandler<TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: DefineApiHandlerInput<TPath, TSchema, TContext> & {
+    method: ApiHandler<TPath, Request, unknown>['method'];
+}): ApiHandler<TPath, Request, unknown>;
+declare const defineApiMethod: <M extends ApiHandler["method"]>(method: M) => <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: DefineApiHandlerInput<TPath, TSchema, TContext> & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const defineGet: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const definePost: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const definePut: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const defineDelete: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const definePatch: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const defineOptions: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const defineHead: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare function json(data: unknown, options?: ResponseOptions): Response;
+export declare function html(content: string, options?: ResponseOptions): Response;
+export declare function redirect(url: string, status?: number): Response;
+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: DefineApiHandlerInput<TPath, TSchema, TContext> & {
+        path: TPath;
+        method: ApiHandler<TPath, Request, unknown>['method'];
+    }): ApiHandler<TPath, Request, unknown>;
+    get: ReturnType<typeof defineApiMethod<'GET'>>;
+    post: ReturnType<typeof defineApiMethod<'POST'>>;
+    put: ReturnType<typeof defineApiMethod<'PUT'>>;
+    delete: ReturnType<typeof defineApiMethod<'DELETE'>>;
+    patch: ReturnType<typeof defineApiMethod<'PATCH'>>;
+    options: ReturnType<typeof defineApiMethod<'OPTIONS'>>;
+    head: ReturnType<typeof defineApiMethod<'HEAD'>>;
+};
+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: (api: GroupDefineHandler<TContext>) => readonly ApiHandler<string, Request, unknown>[];
+}): GroupHandler<TPrefix>;
+export {};

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

@@ -0,0 +1,63 @@
+import { createBodyResponse } from "./create-body-response.js";
+function defineApiHandler(handler) {
+  return handler;
+}
+const defineApiMethod = (method) => (handler) => defineApiHandler({ ...handler, method });
+const defineGet = defineApiMethod("GET");
+const definePost = defineApiMethod("POST");
+const definePut = defineApiMethod("PUT");
+const defineDelete = defineApiMethod("DELETE");
+const definePatch = defineApiMethod("PATCH");
+const defineOptions = defineApiMethod("OPTIONS");
+const defineHead = defineApiMethod("HEAD");
+function json(data, options) {
+  return createBodyResponse("json", data, {
+    status: options?.status,
+    headers: options?.headers
+  });
+}
+function html(content, options) {
+  return createBodyResponse("html", content, {
+    status: options?.status,
+    headers: options?.headers
+  });
+}
+function redirect(url, status = 302) {
+  return new Response(null, {
+    status,
+    headers: { Location: url }
+  });
+}
+function createGroupApi() {
+  const define = ((handler) => handler);
+  return Object.assign(define, {
+    get: defineApiMethod("GET"),
+    post: defineApiMethod("POST"),
+    put: defineApiMethod("PUT"),
+    delete: defineApiMethod("DELETE"),
+    patch: defineApiMethod("PATCH"),
+    options: defineApiMethod("OPTIONS"),
+    head: defineApiMethod("HEAD")
+  });
+}
+function defineGroupHandler(config) {
+  return {
+    prefix: config.prefix,
+    middleware: config.middleware,
+    routes: config.routes(createGroupApi())
+  };
+}
+export {
+  defineApiHandler,
+  defineDelete,
+  defineGet,
+  defineGroupHandler,
+  defineHead,
+  defineOptions,
+  definePatch,
+  definePost,
+  definePut,
+  html,
+  json,
+  redirect
+};

package/src/adapters/shared/{explicit-static-render-preparation.d.ts → http/explicit-static-render-preparation.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { EcoFunctionComponent, EcoPageComponent } from '../../types/public-types.js';
-import type { ExplicitViewRenderer, ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { EcoFunctionComponent, EcoPageComponent } from '../../../types/public-types.js';
+import type { ExplicitViewRenderer, ExplicitViewRendererResolver } from '../../../route-renderer/route-renderer.js';
 type ExplicitStaticRenderPreparationResult = {
     renderer: ExplicitViewRenderer;
     props: Record<string, unknown>;

package/src/adapters/shared/{explicit-static-route-matcher.d.ts → http/explicit-static-route-matcher.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { StaticRoute } from '../../types/public-types.js';
-import type { ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { StaticRoute } from '../../../types/public-types.js';
+import type { ExplicitViewRendererResolver } from '../../../route-renderer/route-renderer.js';
 export declare const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS: {
     readonly missingIntegration: (routePath: string) => string;
     readonly noRendererForIntegration: (integrationName: string) => string;
@@ -27,12 +27,6 @@ export declare class ExplicitStaticRouteMatcher {
      * 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.

package/src/adapters/shared/{explicit-static-route-matcher.js → http/explicit-static-route-matcher.js}

@@ -1,5 +1,6 @@
-import { appLogger } from "../../global/app-logger.js";
+import { appLogger } from "../../../global/app-logger.js";
 import { prepareExplicitStaticRender } from "./explicit-static-render-preparation.js";
+import { matchExplicitStaticPathPattern } from "../../abstract/segment-path-matcher.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}`
@@ -20,49 +21,13 @@ class ExplicitStaticRouteMatcher {
   match(url) {
     const pathname = new URL(url).pathname;
     for (const route of this.staticRoutes) {
-      const params = this.matchRoute(route.path, pathname);
+      const params = matchExplicitStaticPathPattern(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.

package/src/adapters/shared/{file-route-middleware-pipeline.d.ts → http/file-route-middleware-pipeline.d.ts}

@@ -1,5 +1,5 @@
-import type { FileRouteMiddleware, FileRouteMiddlewareContext, RequestLocals } from '../../types/public-types.js';
-import type { PageCacheService } from '../../services/cache/page-cache-service.js';
+import type { FileRouteMiddleware, FileRouteMiddlewareContext, RequestLocals } from '../../../types/public-types.js';
+import type { PageCacheService } from '../../../services/cache/page-cache-service.js';
 export declare const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS: {
     readonly middlewareRequiresDynamic: (filePath: string) => string;
 };

package/src/adapters/shared/{file-route-middleware-pipeline.js → http/file-route-middleware-pipeline.js}

@@ -1,6 +1,7 @@
-import { createRequire } from "../../utils/locals-utils.js";
+import { createRequire } from "../../../utils/locals-utils.js";
 import { ApiResponseBuilder } from "./api-response.js";
-import { LocalsAccessError } from "../../errors/locals-access-error.js";
+import { runMiddlewareChain } from "./run-middleware-chain.js";
+import { LocalsAccessError } from "../../../errors/locals-access-error.js";
 const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
   middlewareRequiresDynamic: (filePath) => `[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`
 };
@@ -46,16 +47,14 @@ class FileRouteMiddlewarePipeline {
       locals: input.locals,
       require: createRequire(() => context.locals),
       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);
+        if (options?.status) context.response.status(options.status);
+        if (options?.headers) context.response.headers(options.headers);
+        return context.response.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);
+        if (options?.status) context.response.status(options.status);
+        if (options?.headers) context.response.headers(options.headers);
+        return context.response.html(content);
       }
     };
     return context;
@@ -70,18 +69,7 @@ class FileRouteMiddlewarePipeline {
    * @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();
+    return runMiddlewareChain(input.middleware, input.context, input.renderResponse);
   }
 }
 export {

package/src/adapters/shared/{fs-server-response-factory.d.ts → http/fs-server-response-factory.d.ts}

@@ -1,5 +1,5 @@
-import type { FileSystemServerOptions } from '../../types/internal-types.js';
-import type { RouteRendererBody } from '../../types/public-types.js';
+import type { FileSystemServerOptions } from '../../../types/internal-types.js';
+import type { RouteRendererBody } from '../../../types/public-types.js';
 /**
  * Builds HTTP responses for static files and shared file-system fallbacks.
  */
@@ -16,6 +16,11 @@ export declare class FileSystemServerResponseFactory {
      * Wraps already-rendered HTML in a 404 response envelope.
      */
     createHtmlNotFoundResponse(body: RouteRendererBody): Promise<Response>;
+    createDefaultServerErrorResponse(): Promise<Response>;
+    /**
+     * Wraps already-rendered HTML in a 500 response envelope.
+     */
+    createHtmlServerErrorResponse(body: RouteRendererBody): Promise<Response>;
     /**
      * Reads a static file response, returning `null` when the file is missing.
      */

package/src/adapters/shared/{fs-server-response-factory.js → http/fs-server-response-factory.js}

@@ -1,5 +1,5 @@
-import { STATUS_MESSAGE } from "../../config/constants.js";
-import { appLogger } from "../../global/app-logger.js";
+import { STATUS_MESSAGE } from "../../../config/constants.js";
+import { appLogger } from "../../../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
 class FileSystemServerResponseFactory {
   options;
@@ -38,6 +38,26 @@ class FileSystemServerResponseFactory {
       }
     });
   }
+  async createDefaultServerErrorResponse() {
+    return new Response(STATUS_MESSAGE[500], {
+      status: 500,
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8"
+      }
+    });
+  }
+  /**
+   * Wraps already-rendered HTML in a 500 response envelope.
+   */
+  async createHtmlServerErrorResponse(body) {
+    return await this.createResponseWithBody(body, {
+      status: 500,
+      statusText: STATUS_MESSAGE[500],
+      headers: {
+        "Content-Type": "text/html"
+      }
+    });
+  }
   /**
    * Reads a static file response, returning `null` when the file is missing.
    */

package/src/adapters/shared/{fs-server-response-matcher.d.ts → http/fs-server-response-matcher.d.ts}

@@ -1,8 +1,8 @@
-import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.js';
-import type { PageRendererResolver } from '../../route-renderer/route-renderer.js';
-import type { RouteRegistry } from '../../router/server/route-registry.js';
-import type { PageCacheService } from '../../services/cache/page-cache-service.js';
-import type { CacheStrategy } from '../../services/cache/cache.types.js';
+import type { EcoPagesAppConfig, MatchResult } from '../../../types/internal-types.js';
+import type { PageRendererResolver } from '../../../route-renderer/route-renderer.js';
+import type { RouteRegistry } from '../../../router/server/route-registry.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 interface FileSystemResponseMatcherOptions {
     appConfig: EcoPagesAppConfig;
@@ -55,6 +55,26 @@ export declare class FileSystemResponseMatcher {
      * when the page template cannot be resolved.
      */
     private renderCustomNotFoundResponse;
+    /**
+     * Renders the app-owned custom 500 page, falling back to the default text 500
+     * when the page template cannot be resolved.
+     */
+    private renderCustomServerErrorResponse;
+    /**
+     * Builds development-only error details for the custom 500 page.
+     * @remarks Production omits these fields so stacks are not serialized into HTML.
+     */
+    private buildServerErrorPageProps;
+    private renderCustomErrorPageResponse;
+    private renderCustomNotFoundResponseOrServerError;
+    /**
+     * Logs the original render failure, then tries the custom 500 page once.
+     * @remarks Any failure while rendering the custom 500 page falls back to the
+     * default plain-text response and never re-enters the custom page path.
+     * In development the thrown error's `message` and `stack` are passed into the
+     * custom 500 page props.
+     */
+    private createInternalServerErrorResponse;
     private createExecutionPlan;
     /**
      * Loads the matched page module for request-time inspection.