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

package/src/route-renderer/page-loading/lazy-entry-collection.js

@@ -0,0 +1,105 @@
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { rapidhash } from "../../utils/hash.js";
+import { getLazyTriggerKey } from "./lazy-trigger-planning.js";
+function isDependencyEntryObject(entry) {
+  return typeof entry === "object" && entry !== null;
+}
+function getDependencyEntrySrcOrThrow(entry, errorMessage) {
+  if (!entry.src) {
+    throw new Error(errorMessage);
+  }
+  return entry.src;
+}
+function collectLazyScriptEntries(options) {
+  const {
+    scriptEntries,
+    componentFile,
+    componentDir,
+    integrationName,
+    dependencies,
+    lazyDependencyKeys,
+    registerLazyScript,
+    resolveDependencyPath,
+    resolveLazyScripts,
+    createModuleScriptAttributes,
+    createEcopagesJsxLazyEntryName,
+    pushUniqueDependency,
+    getLazyScriptMissingSrcMessage,
+    isEcopagesJsxIntegration
+  } = options;
+  for (const [index, scriptEntry] of scriptEntries.entries()) {
+    if (!isDependencyEntryObject(scriptEntry) || !scriptEntry.lazy) {
+      continue;
+    }
+    const lazy = scriptEntry.lazy;
+    const content = scriptEntry.content;
+    const src = scriptEntry.src;
+    const attributes = scriptEntry.attributes;
+    if (content) {
+      const lazyKey2 = `lazy:${rapidhash(`${componentFile}:entry:${index}:${content}`).toString(16)}`;
+      const depKey2 = `lazy:entry:content:${getLazyTriggerKey(lazy)}:${content}:${JSON.stringify(attributes ?? {})}`;
+      pushUniqueDependency(
+        lazyDependencyKeys,
+        depKey2,
+        dependencies,
+        AssetFactory.createContentScript({
+          position: "head",
+          content,
+          excludeFromHtml: true,
+          attributes: {
+            ...createModuleScriptAttributes(attributes),
+            "data-eco-lazy-key": lazyKey2
+          }
+        })
+      );
+      registerLazyScript({
+        lazy,
+        lazyKey: lazyKey2
+      });
+      continue;
+    }
+    const script = src ?? getDependencyEntrySrcOrThrow(scriptEntry, getLazyScriptMissingSrcMessage());
+    const resolvedPath = resolveDependencyPath(componentDir, script);
+    const fallbackUrl = resolveLazyScripts(componentDir, [script]).split(",")[0] ?? "";
+    const lazyKey = `lazy:${rapidhash(`${resolvedPath}:${getLazyTriggerKey(lazy)}`).toString(16)}`;
+    const lazyEntryName = createEcopagesJsxLazyEntryName(
+      integrationName,
+      `${resolvedPath}:${getLazyTriggerKey(lazy)}`
+    );
+    const depKey = `lazy:entry:file:${getLazyTriggerKey(lazy)}:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
+    pushUniqueDependency(
+      lazyDependencyKeys,
+      depKey,
+      dependencies,
+      isEcopagesJsxIntegration(integrationName) ? AssetFactory.createContentScript({
+        name: lazyEntryName,
+        position: "head",
+        content: `import ${JSON.stringify(resolvedPath)};`,
+        excludeFromHtml: true,
+        bundleOptions: {
+          splitting: false
+        },
+        attributes: {
+          ...createModuleScriptAttributes(attributes),
+          "data-eco-lazy-key": lazyKey
+        }
+      }) : AssetFactory.createFileScript({
+        filepath: resolvedPath,
+        position: "head",
+        excludeFromHtml: true,
+        attributes: {
+          ...createModuleScriptAttributes(attributes),
+          "data-eco-lazy-key": lazyKey
+        }
+      })
+    );
+    registerLazyScript({
+      lazy,
+      lazyKey,
+      fallbackUrl
+    });
+  }
+}
+export {
+  collectLazyScriptEntries
+};

package/src/route-renderer/page-loading/lazy-trigger-planning.d.ts

@@ -0,0 +1,19 @@
+import type { DependencyLazyTrigger, EcoComponent, ResolvedLazyTrigger } from '../../types/public-types.js';
+/**
+ * Lazy scripts already normalized onto one trigger and concrete script URL set.
+ */
+export type ResolvedLazyGroup = {
+    lazy: DependencyLazyTrigger;
+    scripts: string[];
+};
+/**
+ * Creates a stable grouping key for a lazy trigger declaration.
+ */
+export declare function getLazyTriggerKey(lazy: DependencyLazyTrigger): string;
+/**
+ * Derives the public lazy-trigger manifest attached to a component config.
+ *
+ * The generated `triggerId` is stable for the same component file and set of
+ * resolved script URLs, independent of declaration order.
+ */
+export declare function buildResolvedLazyTriggers(config: NonNullable<EcoComponent['config']>, groups: ResolvedLazyGroup[]): ResolvedLazyTrigger[];

package/src/route-renderer/page-loading/lazy-trigger-planning.js

@@ -0,0 +1,40 @@
+import { rapidhash } from "../../utils/hash.js";
+function getLazyTriggerKey(lazy) {
+  if ("on:idle" in lazy) {
+    return "on:idle";
+  }
+  if ("on:interaction" in lazy) {
+    return `on:interaction:${lazy["on:interaction"]}`;
+  }
+  if ("on:visible" in lazy) {
+    const value = lazy["on:visible"];
+    return `on:visible:${value === true ? "true" : value}`;
+  }
+  return JSON.stringify(lazy);
+}
+function buildResolvedLazyTriggers(config, groups) {
+  if (groups.length === 0) return [];
+  const componentFile = config.__eco?.file ?? "";
+  const sortedUrls = groups.flatMap((group) => group.scripts).sort().join(",");
+  const triggerId = `eco-trigger-${rapidhash(`${componentFile}:${sortedUrls}`).toString(16)}`;
+  const rules = groups.map((group) => {
+    const { scripts, lazy } = group;
+    if ("on:idle" in lazy) {
+      return { "on:idle": { scripts } };
+    }
+    if ("on:interaction" in lazy) {
+      return { "on:interaction": { value: lazy["on:interaction"], scripts } };
+    }
+    if ("on:visible" in lazy) {
+      const visibleSelector = lazy["on:visible"];
+      if (visibleSelector === true) return { "on:visible": { scripts } };
+      return { "on:visible": { value: String(visibleSelector), scripts } };
+    }
+    throw new Error(`Unknown lazy trigger kind: ${JSON.stringify(lazy)}`);
+  });
+  return [{ triggerId, rules }];
+}
+export {
+  buildResolvedLazyTriggers,
+  getLazyTriggerKey
+};

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

@@ -0,0 +1,5 @@
+import type { EcopagesVirtualImport } from './ecopages-virtual-imports.js';
+/**
+ * Combines explicit config module declarations with auto-detected `ecopages:` imports.
+ */
+export declare function collectModuleDeclarations(modulesMap: Map<string, Set<string> | null>, declaredModules: unknown, autoVirtualImports: EcopagesVirtualImport[]): void;

package/src/route-renderer/page-loading/module-declaration-aggregation.js

@@ -0,0 +1,33 @@
+import { normalizeModuleDeclarations } from "../../eco/module-dependencies.js";
+function getDeclaredModules(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  return value.every((entry) => typeof entry === "string") ? value : void 0;
+}
+function mergeModuleDeclaration(modulesMap, declaration) {
+  const existing = modulesMap.get(declaration.from);
+  if (!declaration.imports || declaration.imports.length === 0) {
+    modulesMap.set(declaration.from, null);
+    return;
+  }
+  if (existing === null) {
+    return;
+  }
+  const merged = existing ?? /* @__PURE__ */ new Set();
+  for (const imported of declaration.imports) {
+    merged.add(imported);
+  }
+  modulesMap.set(declaration.from, merged);
+}
+function collectModuleDeclarations(modulesMap, declaredModules, autoVirtualImports) {
+  for (const declaration of normalizeModuleDeclarations(getDeclaredModules(declaredModules))) {
+    mergeModuleDeclaration(modulesMap, declaration);
+  }
+  for (const declaration of autoVirtualImports) {
+    mergeModuleDeclaration(modulesMap, declaration);
+  }
+}
+export {
+  collectModuleDeclarations
+};

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

@@ -0,0 +1,3 @@
+export declare function createModuleScriptName(from: string, imports: string[] | undefined): string;
+export declare function createNamedImportModuleSource(from: string, imports: string[]): string;
+export declare function createNamespaceImportModuleSource(from: string): string;

package/src/route-renderer/page-loading/module-declaration-scripts.js

@@ -0,0 +1,18 @@
+import { rapidhash } from "../../utils/hash.js";
+function createModuleScriptName(from, imports) {
+  const normalizedImports = imports ? [...imports].sort().join(",") : "*";
+  const hash = rapidhash(`${from}|${normalizedImports}`).toString(16);
+  return `module-${hash}`;
+}
+function createNamedImportModuleSource(from, imports) {
+  const namedImports = [...new Set(imports)].sort().join(", ");
+  return `export { ${namedImports} } from '${from}';`;
+}
+function createNamespaceImportModuleSource(from) {
+  return `export * from '${from}';`;
+}
+export {
+  createModuleScriptName,
+  createNamedImportModuleSource,
+  createNamespaceImportModuleSource
+};

package/src/route-renderer/page-loading/page-dependency-bundling.d.ts

@@ -0,0 +1,13 @@
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.js';
+/**
+ * Returns whether the current integration should collapse eligible page assets into
+ * page-owned bundle entries.
+ */
+export declare function shouldBundlePageDependencies(integrationName: string): boolean;
+/**
+ * Rewrites eligible flat dependency declarations into page-owned stylesheet and script bundles.
+ *
+ * Only assets with the default attribute shape and without explicit packaging roles are
+ * collapsed so integration-specific or lazy behavior keeps its existing ownership model.
+ */
+export declare function packagePageDependencies(dependencies: AssetDefinition[], integrationName: string): AssetDefinition[];

package/src/route-renderer/page-loading/page-dependency-bundling.js

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync } from "node:fs";
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { rapidhash } from "../../utils/hash.js";
+function hasOnlyExpectedAttributes(attributes, expected) {
+  const keys = Object.keys(attributes ?? {});
+  const expectedKeys = Object.keys(expected);
+  if (keys.length !== expectedKeys.length) {
+    return false;
+  }
+  return expectedKeys.every((key) => attributes?.[key] === expected[key]);
+}
+function isSafeBundledStylesheetReference(reference) {
+  return reference.startsWith("/") || reference.startsWith("data:") || reference.startsWith("http://") || reference.startsWith("https://") || reference.startsWith("#");
+}
+function normalizeCssReferenceToken(token) {
+  return token.trim().replace(/^['"]|['"]$/g, "");
+}
+function isSafeBundledStylesheetContent(content) {
+  for (const match of content.matchAll(/@import\s+(?:url\()?['"]?([^'")\s]+)['"]?\)?/g)) {
+    const reference = normalizeCssReferenceToken(match[1] ?? "");
+    if (reference && !isSafeBundledStylesheetReference(reference)) {
+      return false;
+    }
+  }
+  for (const match of content.matchAll(/url\(([^)]+)\)/g)) {
+    const reference = normalizeCssReferenceToken(match[1] ?? "");
+    if (reference && !isSafeBundledStylesheetReference(reference)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isBundleableFileStylesheetAsset(dependency) {
+  return dependency.kind === "stylesheet" && dependency.source === "file";
+}
+function isBundleableFileScriptAsset(dependency) {
+  return dependency.kind === "script" && dependency.source === "file";
+}
+function shouldBundlePageDependencies(integrationName) {
+  return integrationName === "react" || integrationName === "ecopages-jsx";
+}
+function createPageDependencyPackagingPlan(dependencies, integrationName) {
+  const shouldBundleDependencies = process.env.NODE_ENV === "production";
+  const bundleableStyles = dependencies.filter((dependency) => {
+    if (!shouldBundleDependencies) {
+      return false;
+    }
+    if (dependency.kind !== "stylesheet" || dependency.inline || dependency.position === "body") {
+      return false;
+    }
+    if (dependency.packageRole || !hasOnlyExpectedAttributes(dependency.attributes, { rel: "stylesheet" })) {
+      return false;
+    }
+    if (dependency.source === "content") {
+      return isSafeBundledStylesheetContent(dependency.content);
+    }
+    if (!existsSync(dependency.filepath)) {
+      return false;
+    }
+    return isSafeBundledStylesheetContent(readFileSync(dependency.filepath, "utf8"));
+  }).filter(isBundleableFileStylesheetAsset);
+  const bundleableScripts = dependencies.filter((dependency) => {
+    if (!shouldBundleDependencies) {
+      return false;
+    }
+    return dependency.kind === "script" && dependency.source === "file" && !dependency.inline && !dependency.excludeFromHtml && dependency.position !== "body" && !dependency.packageRole && dependency.bundle !== false && hasOnlyExpectedAttributes(dependency.attributes, { type: "module", defer: "" }) && existsSync(dependency.filepath);
+  }).filter(isBundleableFileScriptAsset);
+  const bundledStylesheet = bundleableStyles.length > 1 ? AssetFactory.createContentStylesheet({
+    content: bundleableStyles.map((dependency) => readFileSync(dependency.filepath, "utf8")).join("\n"),
+    position: "head",
+    attributes: { rel: "stylesheet" },
+    packageRole: "page-style",
+    bundledSourceFilepaths: bundleableStyles.map((dependency) => dependency.filepath)
+  }) : void 0;
+  const pageScriptImports = [...new Set(bundleableScripts.map((dependency) => dependency.filepath))];
+  const shouldBundlePageScript = pageScriptImports.length > 0 && bundleableScripts.length > 1;
+  const bundledScript = shouldBundlePageScript ? AssetFactory.createContentScript({
+    name: `${integrationName}-page-${rapidhash(pageScriptImports.join("|")).toString(16)}`,
+    content: pageScriptImports.map((filepath) => `import ${JSON.stringify(filepath)};`).join("\n"),
+    position: "head",
+    attributes: { type: "module", defer: "" },
+    packageRole: "page-script",
+    bundledSourceFilepaths: pageScriptImports
+  }) : void 0;
+  if (!bundledStylesheet && !bundledScript) {
+    return void 0;
+  }
+  return {
+    bundledStylesheet,
+    bundledScript,
+    bundleableStyleFilepaths: new Set(bundleableStyles.map((dependency) => dependency.filepath)),
+    bundleableScriptFilepaths: new Set(pageScriptImports)
+  };
+}
+function applyPageDependencyPackagingPlan(dependencies, plan) {
+  const unifiedDependencies = [];
+  let insertedStylesheet = false;
+  let insertedScript = false;
+  for (const dependency of dependencies) {
+    if (plan.bundledStylesheet && dependency.kind === "stylesheet" && dependency.source === "file" && plan.bundleableStyleFilepaths.has(dependency.filepath)) {
+      if (!insertedStylesheet) {
+        unifiedDependencies.push(plan.bundledStylesheet);
+        insertedStylesheet = true;
+      }
+      continue;
+    }
+    if (plan.bundledScript && dependency.kind === "script" && dependency.source === "file" && plan.bundleableScriptFilepaths.has(dependency.filepath)) {
+      if (!insertedScript) {
+        unifiedDependencies.push(plan.bundledScript);
+        insertedScript = true;
+      }
+      continue;
+    }
+    unifiedDependencies.push(dependency);
+  }
+  if (plan.bundledScript && !insertedScript) {
+    unifiedDependencies.push(plan.bundledScript);
+  }
+  if (plan.bundledStylesheet && !insertedStylesheet) {
+    unifiedDependencies.push(plan.bundledStylesheet);
+  }
+  return unifiedDependencies;
+}
+function packagePageDependencies(dependencies, integrationName) {
+  if (!shouldBundlePageDependencies(integrationName)) {
+    return dependencies;
+  }
+  const plan = createPageDependencyPackagingPlan(dependencies, integrationName);
+  if (!plan) {
+    return dependencies;
+  }
+  return applyPageDependencyPackagingPlan(dependencies, plan);
+}
+export {
+  packagePageDependencies,
+  shouldBundlePageDependencies
+};

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;
+    }>;
+}

package/src/route-renderer/{page-module-loader.js → page-loading/page-module-loader.js}

@@ -1,22 +1,36 @@
-import { invariant } from "../utils/invariant.js";
-import { PageModuleImportService } from "../services/page-module-import.service.js";
+import { invariant } from "../../utils/invariant.js";
+import { getAppModuleLoader } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
 class PageModuleLoaderService {
+  appModuleLoader;
+  appConfig;
+  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, runtimeOrigin) {
     this.appConfig = appConfig;
     this.runtimeOrigin = runtimeOrigin;
-    this.pageModuleImportService = new PageModuleImportService();
+    this.appModuleLoader = getAppModuleLoader(appConfig);
   }
-  pageModuleImportService;
   /**
-   * Imports a page module from source.
-   * Uses direct dynamic import in Bun and transpile+import fallback for other runtimes.
+   * 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.
    */
-  async importPageFile(file) {
+  async importPageFile(file, options) {
     try {
-      return await this.pageModuleImportService.importModule({
+      return await this.appModuleLoader.importModule({
         filePath: file,
         rootDir: this.appConfig.rootDir,
-        outdir: `${this.appConfig.absolutePaths.distDir}/.server-modules`,
+        outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
+        bypassCache: options?.bypassCache,
+        cacheScope: options?.cacheScope,
         transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
         noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`
       });
@@ -25,8 +39,11 @@ class PageModuleLoaderService {
     }
   }
   /**
-   * Executes `getStaticProps` with Ecopages runtime context.
-   * Returns an empty props object when no static props function is defined.
+   * 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.
    */
   async getStaticPropsForPage(options) {
     const { getStaticProps, params } = options;
@@ -42,8 +59,11 @@ class PageModuleLoaderService {
     };
   }
   /**
-   * Builds final page metadata using app-level defaults as a baseline.
-   * If `getMetadata` exists, its result overlays defaults so page-level fields take precedence.
+   * 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.
    */
   async getMetadataPropsForPage(options) {
     const { getMetadata, context } = options;
@@ -79,7 +99,12 @@ class PageModuleLoaderService {
     };
   }
   /**
-   * Resolves render-time page data in order: static props first, then metadata derived from those props.
+   * 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.
    */
   async resolvePageData(options) {
     const { props } = await this.getStaticPropsForPage({

package/src/route-renderer/route-renderer.d.ts

@@ -1,26 +1,69 @@
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
-import type { RouteRenderResult, RouteRendererOptions } from '../public-types.js';
-import type { IntegrationRenderer } from './integration-renderer.js';
-export declare class RouteRenderer {
-    private renderer;
-    constructor(renderer: IntegrationRenderer);
-    createRoute(options: RouteRendererOptions): Promise<RouteRenderResult>;
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { IntegrationRenderer } from './orchestration/integration-renderer.js';
+/**
+ * Narrow route-render contract exposed to higher-level routing code.
+ *
+ * @remarks
+ * Higher-level routing code only needs request execution and page-module
+ * loading. Returning this narrowed shape avoids a dedicated wrapper class while
+ * still keeping callers off the full integration renderer surface.
+ */
+export type PageRouteRenderer = Pick<IntegrationRenderer<unknown>, 'execute' | 'loadPageModule'>;
+/**
+ * Narrow explicit-view render contract exposed to static route handling.
+ *
+ * @remarks
+ * Explicit static routes only need `renderToResponse()`, so the factory can
+ * hide the broader integration renderer surface there as well.
+ */
+export type ExplicitViewRenderer = Pick<IntegrationRenderer<unknown>, 'renderToResponse'>;
+export interface PageRendererResolver {
+    getPageRenderer(filePath: string): PageRouteRenderer;
 }
+export interface ExplicitViewRendererResolver {
+    getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null;
+}
+/**
+ * Combined renderer-factory contract used by static generation.
+ */
+export type StaticGenerationRendererResolver = PageRendererResolver & ExplicitViewRendererResolver;
+/**
+ * Selects and caches integration renderers for route files and explicit views.
+ *
+ * @remarks
+ * The factory owns the policy that maps a route file or explicit integration
+ * name to one initialized integration renderer. Renderer instances are cached by
+ * integration name so repeated requests do not rebuild renderer state.
+ */
 export declare class RouteRendererFactory {
     private appConfig;
     runtimeOrigin: string;
+    private rendererModules?;
     private rendererCache;
-    constructor({ appConfig, runtimeOrigin }: {
+    /**
+     * Creates the route-renderer factory for one app/runtime instance.
+     */
+    constructor({ appConfig, rendererModules, runtimeOrigin, }: {
         appConfig: EcoPagesAppConfig;
+        rendererModules?: unknown;
         runtimeOrigin: string;
     });
-    createRenderer(filePath: string): RouteRenderer;
     /**
-     * Get an integration renderer by its name.
-     * Used for explicit routing where views specify their integration via __eco.integration.
+     * Returns a route renderer for the supplied route file.
+     */
+    getPageRenderer(filePath: string): PageRouteRenderer;
+    /**
+     * Returns a renderer for an explicit view integration.
+     */
+    getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null;
+    /**
+     * Resolves the integration plugin that owns a given route file.
+     */
+    getIntegrationPlugin(filePath: string): AnyIntegrationPlugin;
+    /**
+     * Returns the cached renderer engine for the file's owning integration,
+     * creating it on first use.
      */
-    getRendererByIntegration(integrationName: string): IntegrationRenderer | null;
-    getIntegrationPlugin(filePath: string): IntegrationPlugin;
     private getRouteRendererEngine;
 }