@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

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

@@ -1,16 +1,18 @@
 import { createServer } from "node:http";
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { RESOLVED_ASSETS_DIR } from "../../constants.js";
-import { defaultBuildAdapter } from "../../build/build-adapter.js";
 import { appLogger } from "../../global/app-logger.js";
-import { ProjectWatcher } from "../../watchers/project-watcher.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
-import { NodeHmrManager } from "./node-hmr-manager.js";
 import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
 import { SharedServerAdapter } from "../shared/server-adapter.js";
 import { ServerStaticBuilder } from "../shared/server-static-builder.js";
+import {
+  bindSharedRuntimeHmrManager,
+  initializeSharedRuntimePlugins,
+  installSharedRuntimeBuildExecutor,
+  prepareSharedRuntimePublicDir,
+  startSharedProjectWatching
+} from "../shared/runtime-bootstrap.js";
 import { NodeStaticContentServer } from "./static-content-server.js";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 class ClientAbortError extends Error {
   constructor() {
     super("Client closed the request");
@@ -26,7 +28,6 @@ class NodeServerAdapter extends SharedServerAdapter {
   previewServer = null;
   bridge = null;
   hmrManager = null;
-  processorBuildPlugins = [];
   constructor(options) {
     super(options);
     this.apiHandlers = options.apiHandlers || [];
@@ -47,85 +48,28 @@ class NodeServerAdapter extends SharedServerAdapter {
    *    processors during their `setup()` calls.
    */
   async initialize() {
-    this.setupLoaders();
-    this.copyPublicDir();
-    await this.initializePlugins();
-    await this.initSharedRouter();
-    this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager ?? void 0);
+    installSharedRuntimeBuildExecutor(this.appConfig, {
+      development: this.options?.watch === true
+    });
+    prepareSharedRuntimePublicDir(this.appConfig);
+    await initializeSharedRuntimePlugins({
+      appConfig: this.appConfig,
+      runtimeOrigin: this.runtimeOrigin,
+      hmrManager: this.hmrManager ?? void 0
+    });
+    await this.initializeSharedRouteHandling({
+      staticRoutes: this.staticRoutes,
+      hmrManager: this.hmrManager ?? void 0
+    });
     this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
     this.staticBuilder = new ServerStaticBuilder({
       appConfig: this.appConfig,
       staticSiteGenerator: this.staticSiteGenerator,
-      serveOptions: this.serveOptions
+      serveOptions: this.serveOptions,
+      apiHandlers: this.apiHandlers
     });
     this.initialized = true;
   }
-  /**
-   * Registers every configured file loader as a build plugin on the shared
-   * `defaultBuildAdapter`.
-   *
-   * Loaders are registered on the *shared* adapter (not on a per-build instance)
-   * because they must be available globally to both the SSR build and any dynamic
-   * transpile passes that happen outside of a top-level `build()` call (e.g. HMR
-   * incremental rebuilds).
-   */
-  setupLoaders() {
-    for (const loader of this.appConfig.loaders.values()) {
-      defaultBuildAdapter.registerPlugin(loader);
-    }
-  }
-  copyPublicDir() {
-    const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
-    if (fileSystem.exists(srcPublicDir)) {
-      fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
-    }
-    fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
-  }
-  /**
-   * Sets up all configured processors and integrations in two distinct phases.
-   *
-   * **Phase 1 — Processors:**
-   * Each processor's `setup()` is called first. A processor may expose two
-   * plugin lists:
-   * - `plugins` — transform plugins used during SSR rendering (e.g. PostCSS).
-   * - `buildPlugins` — esbuild plugins used during the client bundle step.
-   * Both are registered on `defaultBuildAdapter` so later build calls pick them up.
-   *
-   * **Phase 2 — Integrations:**
-   * Integrations receive the fully-resolved app config, the runtime origin, and
-   * (if already initialised) the HMR manager before their own `setup()` is called.
-   * This ordering ensures integrations can query config values that processors
-   * may have mutated during phase 1.
-   */
-  async initializePlugins() {
-    const processorBuildPlugins = [];
-    for (const processor of this.appConfig.processors.values()) {
-      await processor.setup();
-      if (processor.plugins) {
-        for (const plugin of processor.plugins) {
-          defaultBuildAdapter.registerPlugin(plugin);
-        }
-      }
-      if (processor.buildPlugins) {
-        processorBuildPlugins.push(...processor.buildPlugins);
-        for (const plugin of processor.buildPlugins) {
-          defaultBuildAdapter.registerPlugin(plugin);
-        }
-      }
-    }
-    for (const integration of this.appConfig.integrations) {
-      integration.setConfig(this.appConfig);
-      integration.setRuntimeOrigin(this.runtimeOrigin);
-      if (this.hmrManager) {
-        integration.setHmrManager(this.hmrManager);
-      }
-      await integration.setup();
-      for (const plugin of integration.plugins) {
-        defaultBuildAdapter.registerPlugin(plugin);
-      }
-    }
-    this.processorBuildPlugins = processorBuildPlugins;
-  }
   getServerOptions() {
     return {
       ...this.serveOptions
@@ -136,9 +80,10 @@ class NodeServerAdapter extends SharedServerAdapter {
       await this.initialize();
     }
     const buildServer = await this.startBuildRuntimeServer();
+    const buildRuntimeOrigin = this.getListeningServerOrigin(buildServer);
     try {
       await this.staticBuilder.build(
-        { preview: false },
+        { preview: false, baseUrl: buildRuntimeOrigin },
         {
           router: this.router,
           routeRendererFactory: this.routeRendererFactory,
@@ -158,12 +103,12 @@ class NodeServerAdapter extends SharedServerAdapter {
       appConfig: this.appConfig,
       options: {
         hostname: this.serveOptions.hostname,
-        port: Number(this.serveOptions.port || 3e3)
+        port: Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT)
       }
     });
     await this.previewServer.start();
-    const previewHostname = this.serveOptions.hostname || "localhost";
-    const previewPort = this.serveOptions.port || 3e3;
+    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
     appLogger.info(`Preview running at http://${previewHostname}:${previewPort}`);
   }
   /**
@@ -254,8 +199,8 @@ class NodeServerAdapter extends SharedServerAdapter {
    * `stopBuildRuntimeServer`, so it never overlaps with the actual dev/prod server.
    */
   async startBuildRuntimeServer() {
-    const hostname = String(this.serveOptions.hostname || "localhost");
-    const port = Number(this.serveOptions.port || 3e3);
+    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
+    const port = 0;
     const server = createServer(async (req, res) => {
       try {
         const webRequest = this.createWebRequest(req);
@@ -275,9 +220,17 @@ class NodeServerAdapter extends SharedServerAdapter {
       });
     });
     this.serverInstance = server;
-    appLogger.info(`Server running at http://${hostname}:${port}`);
+    appLogger.info(`Server running at ${this.getListeningServerOrigin(server)}`);
     return server;
   }
+  getListeningServerOrigin(server) {
+    const address = server.address();
+    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
+    if (!address || typeof address === "string") {
+      throw new Error("Build runtime server did not expose a numeric listening port");
+    }
+    return `http://${hostname}:${address.port}`;
+  }
   /**
    * Gracefully shuts down the ephemeral build runtime server.
    *
@@ -325,12 +278,12 @@ class NodeServerAdapter extends SharedServerAdapter {
    * underlying socket closes early — into a 499 response so it does not
    * incorrectly surface as a 500 in application logs.
    */
-  async handleRequest(_request) {
+  async handleRequest(request) {
     if (!this.initialized) {
       throw new Error("Node server adapter is not initialized. Call createAdapter() first.");
     }
     try {
-      return await this.handleSharedRequest(_request, {
+      return await this.handleSharedRequest(request, {
         apiHandlers: this.apiHandlers,
         errorHandler: this.errorHandler,
         serverInstance: this.serverInstance,
@@ -353,22 +306,23 @@ class NodeServerAdapter extends SharedServerAdapter {
    *   broadcast + heartbeat cleanup.
    * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
    *   rebuilds, notifying connected clients via the bridge.
-   * - `ProjectWatcher` listens for route-level file changes and refreshes the
-   *   router and response handlers when pages are added or removed.
+   * - Shared watcher bootstrapping listens for route-level file changes and
+   *   refreshes the router and response handlers when pages are added or removed.
    *
    * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
    * immediate socket destroy to prevent unhandled upgrade leaks.
    */
-  async completeInitialization(_server) {
-    this.serverInstance = _server;
+  async completeInitialization(server) {
+    this.serverInstance = server;
     if (this.options?.watch) {
+      const { NodeHmrManager } = await import("./node-hmr-manager.js");
       const { WebSocketServer } = await import("ws");
       const wss = new WebSocketServer({ noServer: true });
       this.bridge = new NodeClientBridge();
       this.hmrManager = new NodeHmrManager({ appConfig: this.appConfig, bridge: this.bridge });
       this.hmrManager.setEnabled(true);
       await this.hmrManager.buildRuntime();
-      _server.on("upgrade", (req, socket, head) => {
+      server.on("upgrade", (req, socket, head) => {
         const url = new URL(req.url ?? "/", this.runtimeOrigin);
         if (url.pathname === "/_hmr") {
           wss.handleUpgrade(req, socket, head, (ws) => {
@@ -380,23 +334,17 @@ class NodeServerAdapter extends SharedServerAdapter {
           socket.destroy();
         }
       });
-      const loaderPlugins = Array.from(this.appConfig.loaders.values());
-      const hmrBuildPlugins = [...loaderPlugins, ...this.processorBuildPlugins];
-      this.hmrManager.setPlugins(hmrBuildPlugins);
-      for (const integration of this.appConfig.integrations) {
-        integration.setHmrManager(this.hmrManager);
-      }
+      bindSharedRuntimeHmrManager(this.appConfig, this.hmrManager);
       this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
-      const watcher = new ProjectWatcher({
-        config: this.appConfig,
-        refreshRouterRoutesCallback: async () => {
-          await this.initSharedRouter();
-          this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
-        },
+      await startSharedProjectWatching({
+        appConfig: this.appConfig,
+        refreshRouterRoutesCallback: this.createSharedWatchRefreshCallback({
+          staticRoutes: this.staticRoutes,
+          hmrManager: this.hmrManager
+        }),
         hmrManager: this.hmrManager,
         bridge: this.bridge
       });
-      await watcher.createWatcherSubscription();
     }
     appLogger.debug("Node server adapter initialization completed", {
       apiHandlers: this.apiHandlers.length,
@@ -407,7 +355,7 @@ class NodeServerAdapter extends SharedServerAdapter {
   }
 }
 async function createNodeServerAdapter(params) {
-  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || "localhost"}:${params.serveOptions.port || 3e3}`;
+  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${params.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
   const adapter = new NodeServerAdapter({
     ...params,
     runtimeOrigin

package/src/adapters/node/static-content-server.d.ts

@@ -1,24 +1,60 @@
 import { type Server as NodeHttpServer } from 'node:http';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 type NodeStaticContentServerOptions = {
     hostname?: string;
     port?: number;
 };
+/**
+ * Serves prebuilt static Ecopages output through Node's HTTP server.
+ *
+ * @remarks
+ * This server is used by the Node preview/build path once the app has already
+ * emitted its static output. It intentionally stays small: path sanitization,
+ * content-type selection, optional gzip serving, and 404 handling.
+ */
 export declare class NodeStaticContentServer {
     private readonly appConfig;
     private readonly options;
     private server;
+    /**
+     * Creates the Node static-content server for one built app output directory.
+     */
     constructor({ appConfig, options }: {
         appConfig: EcoPagesAppConfig;
         options?: NodeStaticContentServerOptions;
     });
+    /**
+     * Returns whether the given content type should be served from a pre-gzipped
+     * companion file when available.
+     */
     private shouldServeGzip;
+    /**
+     * Normalizes a request pathname and rejects directory traversal attempts.
+     */
     private sanitizePath;
+    /**
+     * Writes one HTTP response with the provided headers and optional body.
+     */
     private sendResponse;
+    /**
+     * Serves the generated 404 page when present, or a plain-text fallback.
+     */
     private sendNotFoundPage;
+    /**
+     * Serves one concrete file path, honoring gzip and HEAD semantics.
+     */
     private serveFile;
+    /**
+     * Handles one incoming Node HTTP request against the built static output tree.
+     */
     private handleRequest;
+    /**
+     * Starts the static preview server.
+     */
     start(): Promise<NodeHttpServer>;
+    /**
+     * Stops the static preview server and optionally closes active connections.
+     */
     stop(force?: boolean): Promise<void>;
 }
 export {};

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

@@ -1,12 +1,15 @@
 import { createServer } from "node:http";
 import { extname, join, normalize, sep } from "node:path";
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from "../../constants.js";
+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 = {
@@ -14,9 +17,16 @@ class NodeStaticContentServer {
       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);
@@ -25,6 +35,9 @@ class NodeStaticContentServer {
     }
     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)) {
@@ -36,6 +49,9 @@ class NodeStaticContentServer {
     }
     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";
@@ -51,6 +67,9 @@ class NodeStaticContentServer {
     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");
@@ -79,6 +98,9 @@ class NodeStaticContentServer {
     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";
@@ -129,6 +151,9 @@ class NodeStaticContentServer {
     }
     this.sendNotFoundPage(req, res);
   }
+  /**
+   * Starts the static preview server.
+   */
   async start() {
     if (this.server) {
       return this.server;
@@ -141,6 +166,9 @@ class NodeStaticContentServer {
     });
     return this.server;
   }
+  /**
+   * Stops the static preview server and optionally closes active connections.
+   */
   async stop(force = true) {
     if (!this.server) {
       return;

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

@@ -1,4 +1,4 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../public-types.js';
+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;

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

@@ -1,4 +1,4 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteSchema, TypedGroupHandlerContext } from './public-types.js';
+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'> & {

package/src/adapters/shared/explicit-static-render-preparation.d.ts

@@ -0,0 +1,25 @@
+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>;
+    view: EcoFunctionComponent<Record<string, unknown>, any>;
+};
+/**
+ * Resolves the renderer and static props needed to render one explicit static
+ * view at runtime or during static generation.
+ */
+export declare function prepareExplicitStaticRender(input: {
+    routePath: string;
+    view: EcoPageComponent<any>;
+    params: Record<string, string | string[]>;
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    routeRendererFactory: ExplicitViewRendererResolver;
+    errors: {
+        missingIntegration(routePath: string): string;
+        noRendererForIntegration(integrationName: string): string;
+    };
+}): Promise<ExplicitStaticRenderPreparationResult>;
+export {};

package/src/adapters/shared/explicit-static-render-preparation.js

@@ -0,0 +1,26 @@
+function getViewIntegrationName(view) {
+  return view.config?.integration ?? view.config?.__eco?.integration;
+}
+async function prepareExplicitStaticRender(input) {
+  const integrationName = getViewIntegrationName(input.view);
+  if (!integrationName) {
+    throw new Error(input.errors.missingIntegration(input.routePath));
+  }
+  const renderer = input.routeRendererFactory.getExplicitViewRenderer(integrationName);
+  if (!renderer) {
+    throw new Error(input.errors.noRendererForIntegration(integrationName));
+  }
+  const props = input.view.staticProps ? (await input.view.staticProps({
+    pathname: { params: input.params },
+    appConfig: input.appConfig,
+    runtimeOrigin: input.runtimeOrigin
+  })).props : {};
+  return {
+    renderer,
+    props,
+    view: input.view
+  };
+}
+export {
+  prepareExplicitStaticRender
+};

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

@@ -1,19 +1,22 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { StaticRoute } from '../../public-types.js';
-import type { RouteRendererFactory } 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;
 };
 export interface ExplicitStaticRouteMatcherOptions {
     appConfig: EcoPagesAppConfig;
-    routeRendererFactory: RouteRendererFactory;
+    routeRendererFactory: ExplicitViewRendererResolver;
     staticRoutes: StaticRoute[];
 }
 export interface ExplicitRouteMatch {
     route: StaticRoute;
     params: Record<string, string>;
 }
+/**
+ * Matches and renders explicit static routes declared through `app.static()`.
+ */
 export declare class ExplicitStaticRouteMatcher {
     private readonly appConfig;
     private readonly routeRendererFactory;

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

@@ -1,4 +1,5 @@
 import { appLogger } from "../../global/app-logger.js";
+import { prepareExplicitStaticRender } from "./explicit-static-render-preparation.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}`
@@ -71,20 +72,20 @@ class ExplicitStaticRouteMatcher {
     try {
       const mod = await route.loader();
       const view = mod.default;
-      const integrationName = view.config?.__eco?.integration;
-      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 },
+      const {
+        renderer,
+        props,
+        view: renderableView
+      } = await prepareExplicitStaticRender({
+        routePath: route.path,
+        view,
+        params,
         appConfig: this.appConfig,
-        runtimeOrigin: this.appConfig.baseUrl
-      })).props : {};
-      return renderer.renderToResponse(view, props, {});
+        runtimeOrigin: this.appConfig.baseUrl,
+        routeRendererFactory: this.routeRendererFactory,
+        errors: EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS
+      });
+      return renderer.renderToResponse(renderableView, props, {});
     } catch (error) {
       appLogger.error(
         `Error rendering explicit static route ${route.path}:`,

package/src/adapters/shared/file-route-middleware-pipeline.d.ts

@@ -1,8 +1,6 @@
-import type { Middleware, ApiHandlerContext, RequestLocals } from '../../public-types.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 CTX_RENDER_UNAVAILABLE: "[ecopages] ctx.render is not available in file-route middleware";
-    readonly CTX_RENDER_PARTIAL_UNAVAILABLE: "[ecopages] ctx.renderPartial is not available in file-route middleware";
     readonly middlewareRequiresDynamic: (filePath: string) => string;
 };
 /**
@@ -26,7 +24,7 @@ export declare class FileRouteMiddlewarePipeline {
      * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
      */
     assertValidConfiguration(input: {
-        middleware: Middleware[];
+        middleware: FileRouteMiddleware[];
         pageCacheStrategy: 'static' | 'dynamic' | {
             revalidate: number;
             tags?: string[];
@@ -36,9 +34,8 @@ export declare class FileRouteMiddlewarePipeline {
     /**
      * 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.
+     * The context intentionally omits `render()` and `renderPartial()` 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.
@@ -47,7 +44,7 @@ export declare class FileRouteMiddlewarePipeline {
         request: Request;
         params: Record<string, string>;
         locals: RequestLocals;
-    }): ApiHandlerContext;
+    }): FileRouteMiddlewareContext;
     /**
      * Runs the middleware chain and eventually delegates to the render callback.
      *
@@ -58,8 +55,8 @@ export declare class FileRouteMiddlewarePipeline {
      * @returns Response from middleware or final render stage.
      */
     run(input: {
-        middleware: Middleware[];
-        context: ApiHandlerContext;
+        middleware: FileRouteMiddleware[];
+        context: FileRouteMiddlewareContext;
         renderResponse: () => Promise<Response>;
     }): Promise<Response>;
 }

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

@@ -2,11 +2,10 @@ 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 {
+  cacheService;
   constructor(cacheService) {
     this.cacheService = cacheService;
   }
@@ -29,9 +28,8 @@ class FileRouteMiddlewarePipeline {
   /**
    * 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.
+   * The context intentionally omits `render()` and `renderPartial()` 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.
@@ -47,12 +45,6 @@ class FileRouteMiddlewarePipeline {
       },
       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);