@ecopages/core 0.2.0-alpha.2 → 0.2.0-alpha.21

package/src/route-renderer/{render-preparation.service.js → orchestration/render-preparation.service.js}

@@ -1,14 +1,25 @@
 import { createRequire } from "node:module";
+import path from "node:path";
 import {
   AssetFactory
-} from "../services/asset-processing-service/index.js";
-import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from "../eco/global-injector-map.js";
-import { runWithComponentRenderContext } from "../eco/component-render-context.js";
-const coreRequire = createRequire(import.meta.url);
+} from "../../services/assets/asset-processing-service/index.js";
+import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from "../../eco/global-injector-map.js";
+import { BoundaryPlanningService } from "./boundary-planning.service.js";
 class RenderPreparationService {
-  constructor(appConfig, assetProcessingService) {
+  appConfig;
+  assetProcessingService;
+  boundaryPlanningService;
+  /**
+   * Creates the render-preparation orchestrator for one app instance.
+   *
+   * @remarks
+   * The service is app-scoped because it depends on finalized config defaults and
+   * the app-owned asset-processing pipeline while remaining renderer-agnostic.
+   */
+  constructor(appConfig, assetProcessingService, dependencies = {}) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
+    this.boundaryPlanningService = dependencies.boundaryPlanningService ?? new BoundaryPlanningService(appConfig);
   }
   /**
    * Builds the final render options object used by the integration-specific
@@ -30,6 +41,13 @@ class RenderPreparationService {
     const HtmlTemplate = await callbacks.getHtmlTemplate();
     const { props, metadata } = await callbacks.resolvePageData(pageModule, routeOptions);
     const Layout = Page.config?.layout;
+    const boundaryPlan = this.boundaryPlanningService.buildPlan({
+      routeFile: routeOptions.file,
+      currentIntegrationName,
+      HtmlTemplate,
+      Layout,
+      Page
+    });
     const componentsToResolve = Layout ? [HtmlTemplate, Layout, Page] : [HtmlTemplate, Page];
     const resolvedDependencies = await callbacks.resolveDependencies(componentsToResolve);
     const usedIntegrationDependencies = this.collectUsedIntegrationDependencies(
@@ -40,13 +58,13 @@ class RenderPreparationService {
     const allDependencies = [...resolvedDependencies, ...usedIntegrationDependencies, ...pageDeps];
     let componentRender;
     if (callbacks.shouldRenderPageComponent({ Page, Layout, options: routeOptions })) {
-      componentRender = await this.renderPageRoot({
-        currentIntegrationName,
+      const pageRootRender = await this.renderPageRoot({
         Page,
         props,
         routeOptions,
         callbacks
       });
+      componentRender = pageRootRender.componentRender;
       if (componentRender.assets?.length) {
         allDependencies.push(...componentRender.assets);
       }
@@ -56,6 +74,10 @@ class RenderPreparationService {
       const globalAssets = await this.buildGlobalInjectorAssets(triggers, currentIntegrationName);
       allDependencies.push(...globalAssets);
     }
+    const eagerSsrLazyAssets = await this.buildEagerSsrLazyAssets(componentsToResolve, currentIntegrationName);
+    if (eagerSsrLazyAssets.length > 0) {
+      allDependencies.push(...eagerSsrLazyAssets);
+    }
     callbacks.setProcessedDependencies(callbacks.dedupeProcessedAssets(allDependencies));
     const pageProps = {
       ...props,
@@ -82,7 +104,8 @@ class RenderPreparationService {
       pageProps,
       locals,
       pageLocals,
-      cacheStrategy
+      cacheStrategy,
+      boundaryPlan
     };
     return {
       ...integrationSpecificProps,
@@ -102,6 +125,9 @@ class RenderPreparationService {
   collectResolvedTriggers(components, seen = /* @__PURE__ */ new Set()) {
     const triggers = [];
     for (const comp of components) {
+      if (!comp) {
+        continue;
+      }
       const ecoComp = comp;
       if (seen.has(ecoComp)) {
         continue;
@@ -152,6 +178,9 @@ class RenderPreparationService {
   collectIntegrationNames(components, seen = /* @__PURE__ */ new Set()) {
     const integrationNames = /* @__PURE__ */ new Set();
     for (const comp of components) {
+      if (!comp) {
+        continue;
+      }
       const ecoComp = comp;
       if (seen.has(ecoComp)) {
         continue;
@@ -180,12 +209,8 @@ class RenderPreparationService {
    * @returns Structured component render result.
    */
   async renderPageRoot(input) {
-    const execution = await runWithComponentRenderContext(
-      {
-        currentIntegration: input.currentIntegrationName,
-        boundaryContext: input.callbacks.getComponentRenderBoundaryContext()
-      },
-      async () => input.callbacks.renderPageComponent({
+    return {
+      componentRender: await input.callbacks.renderPageComponent({
         component: input.Page,
         props: {
           ...input.props,
@@ -193,8 +218,7 @@ class RenderPreparationService {
           query: input.routeOptions.query || {}
         }
       })
-    );
-    return execution.value;
+    };
   }
   /**
    * Builds the runtime assets needed to bootstrap global lazy trigger execution.
@@ -203,7 +227,7 @@ class RenderPreparationService {
    * @returns Processed assets that should be merged into the final dependency set.
    */
   async buildGlobalInjectorAssets(triggers, currentIntegrationName) {
-    const globalInjectorImportPath = coreRequire.resolve("@ecopages/scripts-injector/global");
+    const globalInjectorImportPath = createRequire(import.meta.url).resolve("@ecopages/scripts-injector/global");
     const globalInjectorRuntimeAsset = AssetFactory.createNodeModuleScript({
       position: "head",
       name: "ecopages-scripts-injector-global",
@@ -237,6 +261,80 @@ class RenderPreparationService {
       currentIntegrationName
     );
   }
+  async buildEagerSsrLazyAssets(components, currentIntegrationName) {
+    const dependencies = this.collectEagerSsrLazyDependencies(components);
+    if (dependencies.length === 0) {
+      return [];
+    }
+    return this.assetProcessingService.processDependencies(dependencies, `${currentIntegrationName}:ssr-lazy`);
+  }
+  collectEagerSsrLazyDependencies(components) {
+    const dependencies = [];
+    const visitedConfigs = /* @__PURE__ */ new Set();
+    const seenKeys = /* @__PURE__ */ new Set();
+    const normalizeAttributes = (attributes) => ({
+      type: "module",
+      defer: "",
+      ...attributes ?? {}
+    });
+    const collect = (config) => {
+      if (!config || visitedConfigs.has(config)) {
+        return;
+      }
+      visitedConfigs.add(config);
+      const componentFile = config.__eco?.file;
+      if (componentFile) {
+        const componentDir = path.dirname(componentFile);
+        for (const script of config.dependencies?.scripts ?? []) {
+          if (typeof script === "string" || !script.lazy || script.ssr !== true) {
+            continue;
+          }
+          const attributes = normalizeAttributes(script.attributes);
+          if (script.content) {
+            const key2 = `content:${script.content}:${JSON.stringify(attributes)}`;
+            if (seenKeys.has(key2)) {
+              continue;
+            }
+            seenKeys.add(key2);
+            dependencies.push(
+              AssetFactory.createContentScript({
+                position: "head",
+                content: script.content,
+                attributes
+              })
+            );
+            continue;
+          }
+          if (!script.src) {
+            continue;
+          }
+          const resolvedPath = path.resolve(componentDir, script.src);
+          const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
+          if (seenKeys.has(key)) {
+            continue;
+          }
+          seenKeys.add(key);
+          dependencies.push(
+            AssetFactory.createFileScript({
+              filepath: resolvedPath,
+              position: "head",
+              attributes
+            })
+          );
+        }
+      }
+      if (config.layout?.config) {
+        collect(config.layout.config);
+      }
+      for (const nestedComponent of config.dependencies?.components ?? []) {
+        collect(nestedComponent?.config);
+      }
+    };
+    for (const component of components) {
+      collect(component.config);
+    }
+    return dependencies;
+  }
 }
 export {
   RenderPreparationService

package/src/route-renderer/orchestration/route-shell-composer.service.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, HtmlTemplateProps, PageMetadataProps } from '../../types/public-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { RenderToResponseContext } from './integration-renderer.js';
+export interface RouteShellComposerCallbacks {
+    hasForeignBoundaryDescendants(component: EcoComponent): boolean;
+    createHtmlResponse(body: BodyInit, ctx: RenderToResponseContext): Response;
+    renderComponentBoundary(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
+    getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
+    resolveViewMetadata<P>(view: EcoComponent<P>, props: P): Promise<PageMetadataProps>;
+    appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+    finalizeResolvedHtml(options: {
+        html: string;
+        partial?: boolean;
+        componentRootAttributes?: Record<string, string>;
+        documentAttributes?: Record<string, string>;
+        transformHtml?: boolean;
+    }): Promise<string>;
+    docType: string;
+}
+export declare class RouteShellComposer {
+    renderPartialViewResponse<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        renderInline?: () => Promise<BodyInit>;
+        transformHtml?: (html: string) => string;
+    }, callbacks: RouteShellComposerCallbacks): Promise<Response>;
+    renderViewWithDocumentShell<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        layout?: EcoComponent;
+    }, callbacks: RouteShellComposerCallbacks): Promise<Response>;
+    renderPageWithDocumentShell(input: {
+        page: {
+            component: EcoComponent;
+            props: Record<string, unknown>;
+        };
+        layout?: {
+            component: EcoComponent;
+            props?: Record<string, unknown>;
+        };
+        htmlTemplate: EcoComponent;
+        metadata: PageMetadataProps;
+        pageProps: Record<string, unknown>;
+        documentProps?: Record<string, unknown>;
+        transformDocumentHtml?: (html: string) => string;
+    }, callbacks: RouteShellComposerCallbacks): Promise<string>;
+}

package/src/route-renderer/orchestration/route-shell-composer.service.js

@@ -0,0 +1,81 @@
+class RouteShellComposer {
+  async renderPartialViewResponse(input, callbacks) {
+    if (input.renderInline && !callbacks.hasForeignBoundaryDescendants(input.view)) {
+      return callbacks.createHtmlResponse(await input.renderInline(), input.ctx);
+    }
+    const rendererCache = /* @__PURE__ */ new Map();
+    const viewRender = await callbacks.renderComponentBoundary({
+      component: input.view,
+      props: input.props ?? {},
+      integrationContext: { rendererCache }
+    });
+    const html = input.transformHtml ? input.transformHtml(viewRender.html) : viewRender.html;
+    return callbacks.createHtmlResponse(html, input.ctx);
+  }
+  async renderViewWithDocumentShell(input, callbacks) {
+    const normalizedProps = input.props ?? {};
+    if (input.ctx.partial) {
+      return this.renderPartialViewResponse(input, callbacks);
+    }
+    await callbacks.prepareViewDependencies(input.view, input.layout);
+    const HtmlTemplate = await callbacks.getHtmlTemplate();
+    const metadata = await callbacks.resolveViewMetadata(input.view, input.props);
+    const rendererCache = /* @__PURE__ */ new Map();
+    const viewRender = await callbacks.renderComponentBoundary({
+      component: input.view,
+      props: normalizedProps,
+      integrationContext: { rendererCache }
+    });
+    const layoutRender = input.layout ? await callbacks.renderComponentBoundary({
+      component: input.layout,
+      props: {},
+      children: viewRender.html,
+      integrationContext: { rendererCache }
+    }) : void 0;
+    const documentRender = await callbacks.renderComponentBoundary({
+      component: HtmlTemplate,
+      props: {
+        metadata,
+        pageProps: normalizedProps
+      },
+      children: layoutRender?.html ?? viewRender.html,
+      integrationContext: { rendererCache }
+    });
+    callbacks.appendProcessedDependencies(viewRender.assets, layoutRender?.assets, documentRender.assets);
+    const html = await callbacks.finalizeResolvedHtml({
+      html: `${callbacks.docType}${documentRender.html}`,
+      partial: false
+    });
+    return callbacks.createHtmlResponse(html, input.ctx);
+  }
+  async renderPageWithDocumentShell(input, callbacks) {
+    const rendererCache = /* @__PURE__ */ new Map();
+    const pageRender = await callbacks.renderComponentBoundary({
+      component: input.page.component,
+      props: input.page.props,
+      integrationContext: { rendererCache }
+    });
+    const layoutRender = input.layout ? await callbacks.renderComponentBoundary({
+      component: input.layout.component,
+      props: input.layout.props ?? {},
+      children: pageRender.html,
+      integrationContext: { rendererCache }
+    }) : void 0;
+    const documentRender = await callbacks.renderComponentBoundary({
+      component: input.htmlTemplate,
+      props: {
+        metadata: input.metadata,
+        pageProps: input.pageProps,
+        ...input.documentProps ?? {}
+      },
+      children: layoutRender?.html ?? pageRender.html,
+      integrationContext: { rendererCache }
+    });
+    callbacks.appendProcessedDependencies(pageRender.assets, layoutRender?.assets, documentRender.assets);
+    const documentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(documentRender.html) : documentRender.html;
+    return `${callbacks.docType}${documentHtml}`;
+  }
+}
+export {
+  RouteShellComposer
+};

package/src/route-renderer/orchestration/template-serialization.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Minimal template-result shape that core can serialize generically.
+ *
+ * @remarks
+ * Core intentionally models only the transport shape used during deferred
+ * cross-integration child passing: alternating static string segments plus
+ * interpolated runtime values. Concrete runtime markers that identify a given
+ * framework's template payload must stay outside core and be registered by the
+ * owning integration package.
+ */
+export type SerializableTemplateShape = {
+    strings: readonly string[];
+    values?: readonly unknown[];
+};
+/**
+ * Integration-owned adapter that teaches core how to serialize one deferred
+ * template payload shape.
+ *
+ * @remarks
+ * The separation here is intentional: core owns the HTML serialization logic,
+ * but integrations own runtime-shape detection. That keeps package-specific
+ * markers such as framework template sentinels out of core while still letting
+ * deferred children round-trip through mixed renderer boundaries.
+ */
+export type DeferredTemplateSerializer<TTemplate extends SerializableTemplateShape = SerializableTemplateShape> = {
+    matches(value: unknown): value is TTemplate;
+    serialize(template: TTemplate, serializeValue: (value: unknown) => string | undefined): string;
+};
+/**
+ * Serializes a generic template shape into HTML.
+ *
+ * @remarks
+ * This handles only HTML reconstruction semantics: quoted attribute values,
+ * boolean attributes, and omission of client-only event or property bindings.
+ * It does not decide whether an arbitrary value belongs to a framework-specific
+ * template runtime; integrations must make that decision before delegating here.
+ */
+export declare function serializeTemplateShape(template: SerializableTemplateShape, serializeValue: (value: unknown) => string | undefined): string;

package/src/route-renderer/orchestration/template-serialization.js

@@ -0,0 +1,45 @@
+import { escapeHtmlAttribute } from "../../utils/html-escaping.js";
+const ATTRIBUTE_TAIL_PATTERN = /(\s+)([@.?!]?)([^\s"'<>/=`@.?!]+)=$/;
+function getSerializableTemplateAttribute(stringPart) {
+  const match = ATTRIBUTE_TAIL_PATTERN.exec(stringPart);
+  if (!match) return void 0;
+  return {
+    leading: stringPart.slice(0, match.index),
+    whitespace: match[1],
+    prefix: match[2],
+    name: match[3]
+  };
+}
+function serializeTemplateShape(template, serializeValue) {
+  const values = template.values ?? [];
+  let html = "";
+  for (let index = 0; index < values.length; index += 1) {
+    const stringPart = template.strings[index] ?? "";
+    const serializedValue = serializeValue(values[index]);
+    const attribute = getSerializableTemplateAttribute(stringPart);
+    if (!attribute) {
+      html += stringPart;
+      html += serializedValue ?? "";
+      continue;
+    }
+    html += attribute.leading;
+    if (attribute.prefix === "@" || attribute.prefix === "!" || attribute.prefix === ".") {
+      continue;
+    }
+    if (attribute.prefix === "?") {
+      if (serializedValue) {
+        html += `${attribute.whitespace}${attribute.name}`;
+      }
+      continue;
+    }
+    if (serializedValue === void 0) {
+      continue;
+    }
+    html += `${attribute.whitespace}${attribute.name}="${escapeHtmlAttribute(serializedValue)}"`;
+  }
+  html += template.strings[values.length] ?? "";
+  return html;
+}
+export {
+  serializeTemplateShape
+};

package/src/route-renderer/{dependency-resolver.d.ts → page-loading/dependency-resolver.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoComponent } from '../public-types.js';
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { AssetProcessingService, ProcessedAsset } from '../services/asset-processing-service/index.js';
+import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { AssetProcessingService, ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 export declare const DEPENDENCY_ERRORS: {
     readonly INVALID_STYLESHEET_ENTRY: "Invalid stylesheet dependency entry: expected src or content";
     readonly INVALID_SCRIPT_ENTRY: "Invalid script dependency entry: expected src or content";
@@ -9,7 +9,18 @@ export declare const DEPENDENCY_ERRORS: {
 export declare class DependencyResolverService {
     private appConfig;
     private assetProcessingService;
+    /**
+     * Creates the dependency resolver used by route and component rendering.
+     *
+     * @remarks
+     * The resolver stays intentionally separate from HTML rendering so component
+     * dependency collection, lazy trigger grouping, and processed-asset generation
+     * can evolve without changing renderer implementations.
+     */
     constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
+    /**
+     * Resolves one dependency path relative to the component that declared it.
+     */
     resolveDependencyPath(componentDir: string, pathUrl: string): string;
     /**
      * Maps lazy script source entries to deterministic fallback public URLs
@@ -20,5 +31,5 @@ export declare class DependencyResolverService {
      * Collects and processes component dependencies (styles, scripts, modules, lazy scripts).
      * Lazy dependencies are always resolved into global-injector trigger maps.
      */
-    processComponentDependencies(components: (EcoComponent | Partial<EcoComponent>)[], integrationName: string): Promise<ProcessedAsset[]>;
+    processComponentDependencies(components: Array<EcoComponent | Partial<EcoComponent> | undefined | null>, integrationName: string): Promise<ProcessedAsset[]>;
 }

package/src/route-renderer/{dependency-resolver.js → page-loading/dependency-resolver.js}

@@ -1,8 +1,8 @@
 import path from "node:path";
 import { readFileSync } from "node:fs";
-import { rapidhash } from "../utils/hash.js";
-import { AssetFactory } from "../services/asset-processing-service/index.js";
-import { normalizeModuleDeclarations } from "../eco/module-dependencies.js";
+import { rapidhash } from "../../utils/hash.js";
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { normalizeModuleDeclarations } from "../../eco/module-dependencies.js";
 import { parseSync } from "oxc-parser";
 const DEPENDENCY_ERRORS = {
   INVALID_STYLESHEET_ENTRY: "Invalid stylesheet dependency entry: expected src or content",
@@ -34,7 +34,12 @@ function extractEcopagesVirtualImports(file) {
     const namedImports = [];
     for (const spec of node.specifiers ?? []) {
       if (spec.type === "ImportSpecifier") {
-        const importedName = spec.imported?.type === "Identifier" ? spec.imported.name : spec.imported?.type === "Literal" ? spec.imported.value : spec.local?.name;
+        let importedName = spec.local?.name;
+        if (spec.imported?.type === "Identifier") {
+          importedName = spec.imported.name;
+        } else if (spec.imported?.type === "Literal") {
+          importedName = spec.imported.value;
+        }
         namedImports.push(importedName);
       }
     }
@@ -62,7 +67,7 @@ function createModuleScriptName(from, imports) {
   return `module-${hash}`;
 }
 function createNamedImportModuleSource(from, imports) {
-  const namedImports = imports.join(", ");
+  const namedImports = [...new Set(imports)].sort().join(", ");
   return `export { ${namedImports} } from '${from}';`;
 }
 function createNamespaceImportModuleSource(from) {
@@ -139,10 +144,23 @@ function buildResolvedLazyTriggers(config, groups) {
   return [{ triggerId, rules }];
 }
 class DependencyResolverService {
+  appConfig;
+  assetProcessingService;
+  /**
+   * Creates the dependency resolver used by route and component rendering.
+   *
+   * @remarks
+   * The resolver stays intentionally separate from HTML rendering so component
+   * dependency collection, lazy trigger grouping, and processed-asset generation
+   * can evolve without changing renderer implementations.
+   */
   constructor(appConfig, assetProcessingService) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
   }
+  /**
+   * Resolves one dependency path relative to the component that declared it.
+   */
   resolveDependencyPath(componentDir, pathUrl) {
     return resolveDependencyPath(componentDir, pathUrl);
   }
@@ -163,6 +181,7 @@ class DependencyResolverService {
     const lazyScriptsByConfig = /* @__PURE__ */ new Map();
     const lazyDependencyKeys = /* @__PURE__ */ new Set();
     for (const component of components) {
+      if (!component) continue;
       const componentFile = component.config?.__eco?.file;
       if (!componentFile) continue;
       const stylesheetDependencyKeys = /* @__PURE__ */ new Set();
@@ -245,14 +264,11 @@ class DependencyResolverService {
               }
               scriptDependencyKeys.add(depKey2);
               dependencies.push(
-                AssetFactory.createContentScript({
+                AssetFactory.createInlineContentScript({
                   position: "head",
                   content,
-                  attributes: {
-                    type: "module",
-                    defer: "",
-                    ...attributes
-                  }
+                  bundle: false,
+                  attributes
                 })
               );
               continue;
@@ -357,7 +373,7 @@ class DependencyResolverService {
         }
         if (dependenciesConfig?.components) {
           for (const nestedComponent of dependenciesConfig.components) {
-            if (nestedComponent.config) {
+            if (nestedComponent?.config) {
               collect(nestedComponent.config);
             }
           }

package/src/route-renderer/page-loading/page-module-loader.d.ts

@@ -0,0 +1,90 @@
+import type { EcoPageFile, GetMetadata, GetMetadataContext, GetStaticProps, PageMetadataProps, RouteRendererOptions, EcoPageComponent } from '../../types/public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Loads route page modules and normalizes their data hooks for rendering.
+ *
+ * @remarks
+ * This service keeps the render pipeline from depending directly on raw module
+ * imports. It owns the shared server-module transpiler setup, the precedence
+ * rules between component statics and module exports, and the normalization of
+ * page props and metadata into one renderer-facing shape.
+ */
+export declare class PageModuleLoaderService {
+    private appModuleLoader;
+    private appConfig;
+    private runtimeOrigin;
+    /**
+     * Creates the page-module loader for one app/runtime instance.
+     *
+     * @param appConfig Finalized app config that owns build and invalidation state.
+     * @param runtimeOrigin Runtime origin exposed to page data hooks.
+     */
+    constructor(appConfig: EcoPagesAppConfig, runtimeOrigin: string);
+    /**
+     * Imports one page module through the shared server-side module loading path.
+     *
+     * @remarks
+     * The underlying transpiler keeps Bun and Node aligned on one framework-owned
+     * loading contract even though the runtime-specific execution transport differs.
+     */
+    importPageFile(file: string, options?: {
+        bypassCache?: boolean;
+        cacheScope?: string;
+    }): Promise<EcoPageFile>;
+    /**
+     * Executes the page's static-props hook with Ecopages runtime context.
+     *
+     * @remarks
+     * Pages without a static-props hook still return a normalized empty props
+     * object so downstream render preparation does not branch on hook presence.
+     */
+    getStaticPropsForPage(options: {
+        getStaticProps?: GetStaticProps<Record<string, unknown>>;
+        params?: RouteRendererOptions['params'];
+    }): Promise<{
+        props: Record<string, unknown>;
+        metadata?: PageMetadataProps;
+    }>;
+    /**
+     * Builds the final page metadata object for one render request.
+     *
+     * @remarks
+     * App-level default metadata forms the baseline, then page-level metadata is
+     * overlaid so route-specific fields win without dropping global defaults.
+     */
+    getMetadataPropsForPage(options: {
+        getMetadata: GetMetadata | undefined;
+        context: GetMetadataContext;
+    }): Promise<PageMetadataProps>;
+    /**
+     * Loads a page module and normalizes integration-facing exports.
+     * When both component static methods and module exports exist, component statics win.
+     */
+    resolvePageModule(options: {
+        file: string;
+        importPageFileFn?: (file: string) => Promise<EcoPageFile>;
+    }): Promise<{
+        Page: EcoPageFile['default'] | EcoPageComponent<any>;
+        getStaticProps?: GetStaticProps<Record<string, unknown>>;
+        getMetadata?: GetMetadata;
+        integrationSpecificProps: Record<string, unknown>;
+    }>;
+    /**
+     * Resolves the page data needed by the render pipeline.
+     *
+     * @remarks
+     * Static props are resolved first because page metadata may depend on those
+     * props. This preserves the same ordering whether data hooks are declared as
+     * component statics or module exports.
+     */
+    resolvePageData(options: {
+        pageModule: {
+            getStaticProps?: GetStaticProps<Record<string, unknown>>;
+            getMetadata?: GetMetadata;
+        };
+        routeOptions: RouteRendererOptions;
+    }): Promise<{
+        props: Record<string, unknown>;
+        metadata: PageMetadataProps;
+    }>;
+}