@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

package/src/route-renderer/page-loading/ecopages-virtual-imports.d.ts

@@ -0,0 +1,11 @@
+export type EcopagesVirtualImport = {
+    from: string;
+    imports: string[] | undefined;
+};
+/**
+ * Extracts runtime `ecopages:` virtual-module imports from a component source file.
+ *
+ * Type-only imports are skipped and bare namespace imports are represented by an
+ * `undefined` import list so downstream module generation can preserve that shape.
+ */
+export declare function extractEcopagesVirtualImports(file: string): EcopagesVirtualImport[];

package/src/route-renderer/page-loading/ecopages-virtual-imports.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { parseSync } from "oxc-parser";
+function extractEcopagesVirtualImports(file) {
+  let source;
+  try {
+    source = readFileSync(file, "utf-8");
+  } catch {
+    return [];
+  }
+  let result;
+  try {
+    result = parseSync(file, source, { sourceType: "module" });
+  } catch {
+    return [];
+  }
+  const found = /* @__PURE__ */ new Map();
+  for (const node of result.program.body ?? []) {
+    if (node.type !== "ImportDeclaration") continue;
+    if (node.importKind === "type") continue;
+    const specifier = node.source?.value ?? "";
+    if (!specifier.startsWith("ecopages:")) continue;
+    if (found.get(specifier) === null) {
+      continue;
+    }
+    const namedImports = [];
+    for (const spec of node.specifiers ?? []) {
+      if (spec.type === "ImportSpecifier") {
+        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);
+      }
+    }
+    if (namedImports.length === 0) {
+      found.set(specifier, null);
+      continue;
+    }
+    const existing = found.get(specifier);
+    if (!existing) {
+      found.set(specifier, new Set(namedImports));
+      continue;
+    }
+    for (const imported of namedImports) {
+      existing.add(imported);
+    }
+  }
+  return Array.from(found.entries()).map(([from, importsSet]) => ({
+    from,
+    imports: importsSet ? Array.from(importsSet) : void 0
+  }));
+}
+export {
+  extractEcopagesVirtualImports
+};

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

@@ -0,0 +1,45 @@
+import type { DependencyLazyTrigger, EcoComponentScriptEntry } from '../../types/public-types.js';
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.js';
+type LazyScriptRef = {
+    lazyKey: string;
+    fallbackUrl?: string;
+};
+/**
+ * Lazy scripts grouped by one trigger declaration.
+ */
+export type LazyGroup = {
+    lazy: DependencyLazyTrigger;
+    scripts: LazyScriptRef[];
+};
+/**
+ * Callback used to record one normalized lazy-script registration.
+ */
+export type RegisterLazyScript = (input: {
+    lazy: DependencyLazyTrigger;
+    lazyKey: string;
+    fallbackUrl?: string;
+}) => void;
+type CollectLazyEntriesOptions = {
+    scriptEntries: Array<string | EcoComponentScriptEntry>;
+    componentFile: string;
+    componentDir: string;
+    integrationName: string;
+    dependencies: AssetDefinition[];
+    lazyDependencyKeys: Set<string>;
+    registerLazyScript: RegisterLazyScript;
+    resolveDependencyPath: (componentDir: string, pathUrl: string) => string;
+    resolveLazyScripts: (componentDir: string, scripts: string[]) => string;
+    createModuleScriptAttributes: (attributes?: Record<string, string>) => Record<string, string>;
+    createEcopagesJsxLazyEntryName: (integrationName: string, key: string) => string;
+    pushUniqueDependency: (keys: Set<string>, key: string, dependencies: AssetDefinition[], dependency: AssetDefinition) => boolean;
+    getLazyScriptMissingSrcMessage: () => string;
+    isEcopagesJsxIntegration: (integrationName: string) => boolean;
+};
+/**
+ * Collects lazy script dependency entries and emits their hidden bundle inputs.
+ *
+ * This helper also reports the trigger-to-script relationship back to the caller so
+ * later stages can build the lazy-trigger manifest without reparsing dependency config.
+ */
+export declare function collectLazyScriptEntries(options: CollectLazyEntriesOptions): void;
+export {};

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

@@ -1,5 +1,5 @@
-import type { EcoPageFile, GetMetadata, GetMetadataContext, GetStaticProps, PageMetadataProps, RouteRendererOptions, EcoPageComponent } from '../../public-types.js';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+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.
  *
@@ -10,7 +10,7 @@ import type { EcoPagesAppConfig } from '../../internal-types.js';
  * page props and metadata into one renderer-facing shape.
  */
 export declare class PageModuleLoaderService {
-    private serverModuleTranspiler;
+    private appModuleLoader;
     private appConfig;
     private runtimeOrigin;
     /**
@@ -27,7 +27,10 @@ export declare class PageModuleLoaderService {
      * 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): Promise<EcoPageFile>;
+    importPageFile(file: string, options?: {
+        bypassCache?: boolean;
+        cacheScope?: string;
+    }): Promise<EcoPageFile>;
     /**
      * Executes the page's static-props hook with Ecopages runtime context.
      *

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

@@ -1,8 +1,8 @@
 import { invariant } from "../../utils/invariant.js";
-import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import { getAppModuleLoader } from "../../services/module-loading/app-server-module-transpiler.service.js";
 import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
 class PageModuleLoaderService {
-  serverModuleTranspiler;
+  appModuleLoader;
   appConfig;
   runtimeOrigin;
   /**
@@ -14,7 +14,7 @@ class PageModuleLoaderService {
   constructor(appConfig, runtimeOrigin) {
     this.appConfig = appConfig;
     this.runtimeOrigin = runtimeOrigin;
-    this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
+    this.appModuleLoader = getAppModuleLoader(appConfig);
   }
   /**
    * Imports one page module through the shared server-side module loading path.
@@ -23,11 +23,14 @@ class PageModuleLoaderService {
    * 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.serverModuleTranspiler.importModule({
+      return await this.appModuleLoader.importModule({
         filePath: file,
+        rootDir: this.appConfig.rootDir,
         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}`
       });

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

@@ -1,26 +1,33 @@
-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 { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { IntegrationRenderer } from './orchestration/integration-renderer.js';
 /**
- * Thin wrapper around one initialized integration renderer.
+ * Narrow route-render contract exposed to higher-level routing code.
  *
  * @remarks
- * This type exists so higher-level routing code can ask for a route renderer
- * without depending on the full integration plugin lifecycle. It delegates all
- * real work to the integration-specific renderer selected by the factory.
+ * 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 declare class RouteRenderer {
-    private renderer;
-    /**
-     * Creates a route renderer bound to one integration renderer instance.
-     */
-    constructor(renderer: IntegrationRenderer);
-    /**
-     * Executes the render pipeline for one matched route.
-     */
-    createRoute(options: RouteRendererOptions): Promise<RouteRenderResult>;
+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.
  *
@@ -32,27 +39,28 @@ export declare class RouteRenderer {
 export declare class RouteRendererFactory {
     private appConfig;
     runtimeOrigin: string;
+    private rendererModules?;
     private rendererCache;
     /**
      * Creates the route-renderer factory for one app/runtime instance.
      */
-    constructor({ appConfig, runtimeOrigin }: {
+    constructor({ appConfig, rendererModules, runtimeOrigin, }: {
         appConfig: EcoPagesAppConfig;
+        rendererModules?: unknown;
         runtimeOrigin: string;
     });
     /**
      * Returns a route renderer for the supplied route file.
      */
-    createRenderer(filePath: string): RouteRenderer;
+    getPageRenderer(filePath: string): PageRouteRenderer;
     /**
-     * Get an integration renderer by its name.
-     * Used for explicit routing where views specify their integration via __eco.integration.
+     * Returns a renderer for an explicit view integration.
      */
-    getRendererByIntegration(integrationName: string): IntegrationRenderer | null;
+    getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null;
     /**
      * Resolves the integration plugin that owns a given route file.
      */
-    getIntegrationPlugin(filePath: string): IntegrationPlugin;
+    getIntegrationPlugin(filePath: string): AnyIntegrationPlugin;
     /**
      * Returns the cached renderer engine for the file's owning integration,
      * creating it on first use.