@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/services/module-loading/app-server-module-transpiler.service.js

@@ -0,0 +1,151 @@
+import { getAppBuildExecutor } from "../../build/build-adapter.js";
+import path from "node:path";
+import { createForeignJsxOverridePlugin } from "../../plugins/foreign-jsx-override-plugin.js";
+import { DevelopmentInvalidationService } from "../invalidation/development-invalidation.service.js";
+import {} from "./app-module-loader.service.js";
+import { createAppNodeBootstrapPlugin } from "./node-bootstrap-plugin.js";
+import { PageModuleImportService } from "./page-module-import.service.js";
+import { supportsSourceModuleLoading } from "./source-module-support.js";
+import { ServerModuleTranspiler } from "./server-module-transpiler.service.js";
+function shouldAppUseHostModuleLoader(appConfig, filePath) {
+  if (appConfig.runtime?.hostModuleLoader) {
+    return supportsSourceModuleLoading(filePath);
+  }
+  const normalizedFilePath = path.normalize(filePath);
+  const frameworkOwnedDirectories = [
+    appConfig.absolutePaths.pagesDir,
+    appConfig.absolutePaths.includesDir,
+    appConfig.absolutePaths.layoutsDir,
+    appConfig.absolutePaths.componentsDir
+  ].map((directoryPath) => path.normalize(directoryPath));
+  const isFrameworkOwnedModule = frameworkOwnedDirectories.some((directoryPath) => {
+    return normalizedFilePath === directoryPath || normalizedFilePath.startsWith(`${directoryPath}${path.sep}`);
+  });
+  const isConfiguredTemplateModule = appConfig.templatesExt.some(
+    (extension) => normalizedFilePath.endsWith(extension)
+  );
+  return !(isFrameworkOwnedModule && isConfiguredTemplateModule);
+}
+function getAppHostModuleLoader(appConfig) {
+  return appConfig.runtime?.hostModuleLoader;
+}
+function getAppModuleLoaderOwner(appConfig) {
+  return getAppHostModuleLoader(appConfig) ? "host" : "bun";
+}
+function setAppHostModuleLoader(appConfig, hostModuleLoader) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    hostModuleLoader
+  };
+}
+function getOwningIntegration(appConfig, filePath) {
+  return appConfig.integrations?.flatMap(
+    (integration) => integration.extensions.filter((extension) => filePath.endsWith(extension)).map((extension) => ({ integration, extension }))
+  ).sort((left, right) => right.extension.length - left.extension.length)[0]?.integration;
+}
+function getBunOwnedJsxPlugins(appConfig) {
+  const jsxExtensions = (appConfig.integrations ?? []).filter((integration) => integration.jsxImportSource).flatMap(
+    (integration) => integration.extensions.filter((extension) => extension.endsWith(".tsx") || extension.endsWith(".jsx")).map((extension) => ({ integration, extension }))
+  ).sort((left, right) => right.extension.length - left.extension.length);
+  return jsxExtensions.map(
+    ({ integration, extension }) => createForeignJsxOverridePlugin({
+      hostJsxImportSource: integration.jsxImportSource,
+      foreignExtensions: [extension],
+      excludeExtensions: jsxExtensions.filter((candidate) => candidate.extension.length > extension.length).filter((candidate) => candidate.extension.endsWith(extension)).map((candidate) => candidate.extension),
+      name: `ecopages-bun-jsx-ownership-${integration.name}-${extension.replace(/[^a-zA-Z0-9]+/g, "-")}`
+    })
+  );
+}
+function createAppModuleLoader(appConfig) {
+  const invalidationService = new DevelopmentInvalidationService(appConfig);
+  const pageModuleImportService = new PageModuleImportService({
+    canLoadSourceModuleFromHost: (filePath) => shouldAppUseHostModuleLoader(appConfig, filePath),
+    getHostModuleLoader: () => getAppHostModuleLoader(appConfig)
+  });
+  const getDefaultPlugins = typeof Bun === "undefined" && appConfig.rootDir ? () => [createAppNodeBootstrapPlugin(appConfig)] : () => [];
+  const appLoaderPlugins = Array.from(appConfig.loaders?.values() ?? []);
+  const bunOwnedJsxPlugins = typeof Bun !== "undefined" ? getBunOwnedJsxPlugins(appConfig) : [];
+  const appModuleLoader = {
+    get owner() {
+      return getAppModuleLoaderOwner(appConfig);
+    },
+    pageModuleImportService,
+    async importModule(options) {
+      const invalidationVersion = options.invalidationVersion ?? invalidationService.getServerModuleInvalidationVersion();
+      const owningIntegration = getOwningIntegration(appConfig, options.filePath);
+      const owningJsxImportSource = owningIntegration?.jsxImportSource;
+      const mergedPlugins = [
+        ...getDefaultPlugins(),
+        ...appLoaderPlugins,
+        ...bunOwnedJsxPlugins,
+        ...options.plugins ?? []
+      ];
+      return await pageModuleImportService.importModule({
+        ...options,
+        ...mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {},
+        ...typeof Bun !== "undefined" && owningJsxImportSource ? {
+          jsx: {
+            development: process.env.NODE_ENV === "development",
+            importSource: owningJsxImportSource,
+            runtime: "automatic"
+          }
+        } : {},
+        buildExecutor: options.buildExecutor ?? getAppBuildExecutor(appConfig),
+        invalidationVersion
+      });
+    },
+    invalidateDevelopmentGraph() {
+      pageModuleImportService.invalidateDevelopmentGraph();
+    }
+  };
+  return appModuleLoader;
+}
+function getAppModuleLoader(appConfig) {
+  const existingModuleLoader = appConfig.runtime?.appModuleLoader;
+  if (existingModuleLoader) {
+    return existingModuleLoader;
+  }
+  const appModuleLoader = createAppModuleLoader(appConfig);
+  setAppModuleLoader(appConfig, appModuleLoader);
+  return appModuleLoader;
+}
+function setAppModuleLoader(appConfig, appModuleLoader) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    appModuleLoader
+  };
+}
+function createAppServerModuleTranspiler(appConfig) {
+  const invalidationService = new DevelopmentInvalidationService(appConfig);
+  return new ServerModuleTranspiler({
+    rootDir: appConfig.rootDir,
+    invalidateModules: (changedFiles) => invalidationService.invalidateServerModules(changedFiles),
+    pageModuleImportService: getAppModuleLoader(appConfig)
+  });
+}
+function getAppServerModuleTranspiler(appConfig) {
+  const existingTranspiler = appConfig.runtime?.serverModuleTranspiler;
+  if (existingTranspiler) {
+    return existingTranspiler;
+  }
+  const serverModuleTranspiler = createAppServerModuleTranspiler(appConfig);
+  setAppServerModuleTranspiler(appConfig, serverModuleTranspiler);
+  return serverModuleTranspiler;
+}
+function setAppServerModuleTranspiler(appConfig, serverModuleTranspiler) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    serverModuleTranspiler
+  };
+}
+export {
+  createAppModuleLoader,
+  createAppServerModuleTranspiler,
+  getAppHostModuleLoader,
+  getAppModuleLoader,
+  getAppServerModuleTranspiler,
+  setAppHostModuleLoader,
+  setAppModuleLoader,
+  setAppServerModuleTranspiler,
+  shouldAppUseHostModuleLoader
+};

package/src/services/module-loading/host-module-loader-registry.d.ts

@@ -0,0 +1,4 @@
+import type { SourceModuleLoader } from './module-loading-types.js';
+export declare function setHostModuleLoader(loader: SourceModuleLoader): void;
+export declare function getHostModuleLoader(): SourceModuleLoader | undefined;
+export declare function clearHostModuleLoader(): void;

package/src/services/module-loading/host-module-loader-registry.js

@@ -0,0 +1,15 @@
+let hostModuleLoader;
+function setHostModuleLoader(loader) {
+  hostModuleLoader = loader;
+}
+function getHostModuleLoader() {
+  return hostModuleLoader;
+}
+function clearHostModuleLoader() {
+  hostModuleLoader = void 0;
+}
+export {
+  clearHostModuleLoader,
+  getHostModuleLoader,
+  setHostModuleLoader
+};

package/src/services/module-loading/module-loading-types.d.ts

@@ -0,0 +1,2 @@
+export type SourceModuleLoader = (id: string) => Promise<unknown>;
+export type SourceModuleLoaderFactory = () => SourceModuleLoader | undefined;

package/src/services/module-loading/node-bootstrap-plugin.d.ts

@@ -0,0 +1,42 @@
+import type { EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Returns the app-local node_modules directory used by framework-owned Node
+ * bootstrap loads outside the thin-host manifest path.
+ */
+export declare function getAppRuntimeNodeModulesDir(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>): string;
+export interface NodeBootstrapResolutionOptions {
+    /**
+     * App root used as the fallback package boundary when an importer does not
+     * live under a more specific package.json.
+     */
+    projectDir: string;
+    /**
+     * Runtime-local node_modules directory that receives symlinks to resolved
+     * package roots so transpiled Node imports share one package graph.
+     */
+    runtimeNodeModulesDir: string;
+}
+/**
+ * Builds the user-facing error for Bun-native imports that cannot run on the
+ * Node bootstrap transpile path.
+ */
+export declare function getNodeUnsupportedBuiltinError(specifier: string, importer?: string): string;
+export declare function resolveNodeBootstrapDependency(args: Pick<EcoBuildOnResolveArgs, 'path' | 'importer'>, options: NodeBootstrapResolutionOptions): EcoBuildOnResolveResult | undefined;
+/**
+ * Creates the Node bootstrap plugin used by app-owned server module loads.
+ *
+ * The resolver anchors third-party imports to the nearest package boundary for
+ * the importing file, then mirrors the resolved package root into the runtime
+ * node_modules directory. That keeps transpiled Node execution aligned with the
+ * package graph each source file was authored against.
+ */
+export declare function createNodeBootstrapPlugin(options: NodeBootstrapResolutionOptions): EcoBuildPlugin;
+/**
+ * Creates the default Node bootstrap plugin for one Ecopages app runtime.
+ *
+ * This binds the shared resolution policy to the app's internal execution
+ * directory so transpiled server modules can externalize packages into one
+ * stable runtime node_modules graph.
+ */
+export declare function createAppNodeBootstrapPlugin(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>): EcoBuildPlugin;

package/src/services/module-loading/node-bootstrap-plugin.js

@@ -0,0 +1,297 @@
+import path from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
+function getAppRuntimeNodeModulesDir(appConfig) {
+  return path.join(resolveInternalExecutionDir(appConfig), "node_modules");
+}
+function getPackageNameFromSpecifier(specifier) {
+  if (specifier.startsWith("@")) {
+    const [scope, name] = specifier.split("/");
+    return `${scope}/${name}`;
+  }
+  return specifier.split("/")[0] ?? specifier;
+}
+function findPackageRoot(resolvedPath) {
+  let currentPath = path.dirname(resolvedPath);
+  while (true) {
+    const packageJsonPath = path.join(currentPath, "package.json");
+    if (existsSync(packageJsonPath)) {
+      return currentPath;
+    }
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      throw new Error(`Could not find package root for resolved dependency path: ${resolvedPath}`);
+    }
+    currentPath = parentPath;
+  }
+}
+function pathEntryExists(filePath) {
+  try {
+    lstatSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function linkPointsToPackage(linkPath, packageRoot) {
+  try {
+    return realpathSync(linkPath) === realpathSync(packageRoot);
+  } catch {
+    return false;
+  }
+}
+function ensureRuntimePackageLink(nodeModulesDir, specifier, resolvedPath) {
+  const packageName = getPackageNameFromSpecifier(specifier);
+  const packageRoot = findPackageRoot(resolvedPath);
+  const linkPath = path.join(nodeModulesDir, packageName);
+  mkdirSync(path.dirname(linkPath), { recursive: true });
+  if (pathEntryExists(linkPath)) {
+    if (linkPointsToPackage(linkPath, packageRoot)) {
+      return;
+    }
+    removeRuntimePackageLink(linkPath);
+  }
+  try {
+    symlinkSync(packageRoot, linkPath, "dir");
+  } catch (error) {
+    if (error.code !== "EEXIST") {
+      throw error;
+    }
+    if (linkPointsToPackage(linkPath, packageRoot)) {
+      return;
+    }
+    removeRuntimePackageLink(linkPath);
+    symlinkSync(packageRoot, linkPath, "dir");
+  }
+}
+function removeRuntimePackageLink(linkPath) {
+  try {
+    const stats = lstatSync(linkPath);
+    if (stats.isSymbolicLink()) {
+      unlinkSync(linkPath);
+      return;
+    }
+  } catch {
+    return;
+  }
+  rmSync(linkPath, { recursive: true, force: true });
+}
+function getNodeUnsupportedBuiltinError(specifier, importer) {
+  return `Node bootstrap transpilation does not support Bun builtin specifier ${JSON.stringify(specifier)}${importer ? ` imported from ${importer}` : ""}.`;
+}
+function resolveSpecifier(specifier, parentPath) {
+  try {
+    return createRequire(parentPath).resolve(specifier);
+  } catch {
+    return fileURLToPath(import.meta.resolve(specifier, pathToFileURL(parentPath).href));
+  }
+}
+function resolveFromCore(specifier) {
+  return createRequire(import.meta.url).resolve(specifier);
+}
+function readPackageManifest(packageDir) {
+  const packageJsonPath = path.join(packageDir, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function findInstalledPackageDir(packageName, parentPath) {
+  let currentPath = path.dirname(parentPath);
+  const packageSegments = packageName.split("/");
+  while (true) {
+    const candidateDir = path.join(currentPath, "node_modules", ...packageSegments);
+    if (existsSync(path.join(candidateDir, "package.json"))) {
+      return candidateDir;
+    }
+    const nextPath = path.dirname(currentPath);
+    if (nextPath === currentPath) {
+      return void 0;
+    }
+    currentPath = nextPath;
+  }
+}
+function resolvePackageExportTarget(packageDir, target) {
+  if (typeof target === "string") {
+    return path.resolve(packageDir, target);
+  }
+  if (Array.isArray(target)) {
+    for (const candidate of target) {
+      const resolvedTarget = resolvePackageExportTarget(packageDir, candidate);
+      if (resolvedTarget) {
+        return resolvedTarget;
+      }
+    }
+    return void 0;
+  }
+  if (!target || typeof target !== "object") {
+    return void 0;
+  }
+  const record = target;
+  return resolvePackageExportTarget(packageDir, record.import) ?? resolvePackageExportTarget(packageDir, record.default) ?? resolvePackageExportTarget(packageDir, record.require);
+}
+function resolveInstalledPackageTarget(specifier, parentPath) {
+  const packageName = getPackageNameFromSpecifier(specifier);
+  const packageDir = findInstalledPackageDir(packageName, parentPath);
+  if (!packageDir) {
+    return void 0;
+  }
+  const manifest = readPackageManifest(packageDir);
+  if (!manifest) {
+    return void 0;
+  }
+  const subpath = specifier === packageName ? "." : `./${specifier.slice(packageName.length + 1)}`;
+  const exportsField = manifest.exports;
+  if (exportsField !== void 0) {
+    const exportsRecord = exportsField;
+    const hasSubpathKeys = typeof exportsField === "object" && exportsField !== null && Object.keys(exportsRecord).some((key) => key.startsWith("."));
+    const exportTarget = hasSubpathKeys ? resolvePackageExportTarget(packageDir, exportsRecord[subpath]) : subpath === "." ? resolvePackageExportTarget(packageDir, exportsField) : void 0;
+    if (exportTarget && existsSync(exportTarget)) {
+      return exportTarget;
+    }
+  }
+  if (subpath !== ".") {
+    return void 0;
+  }
+  const mainTarget = manifest.module ?? manifest.main ?? "index.js";
+  const resolvedMainTarget = path.resolve(packageDir, mainTarget);
+  return existsSync(resolvedMainTarget) ? resolvedMainTarget : void 0;
+}
+function findResolutionParent(importer, projectDir) {
+  if (!importer || !path.isAbsolute(importer)) {
+    return path.join(projectDir, "package.json");
+  }
+  let currentPath = path.dirname(importer);
+  while (true) {
+    const packageJsonPath = path.join(currentPath, "package.json");
+    if (existsSync(packageJsonPath)) {
+      return packageJsonPath;
+    }
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      return path.join(projectDir, "package.json");
+    }
+    currentPath = parentPath;
+  }
+}
+function getBootstrapBuildLoaderForPath(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "ts";
+    case ".tsx":
+      return "tsx";
+    case ".jsx":
+      return "jsx";
+    case ".json":
+      return "json";
+    default:
+      return "js";
+  }
+}
+function shouldRewriteBootstrapSource(filePath, projectDir) {
+  const normalizedPath = path.resolve(filePath);
+  const normalizedProjectDir = path.resolve(projectDir);
+  return normalizedPath.startsWith(`${normalizedProjectDir}${path.sep}`) && !normalizedPath.includes(`${path.sep}node_modules${path.sep}`);
+}
+function resolveNodeBootstrapDependency(args, options) {
+  if (args.path.startsWith("./") || args.path.startsWith("../") || args.path.startsWith("@/") || args.path.startsWith("/") || args.path.startsWith("node:")) {
+    return void 0;
+  }
+  const resolveParent = findResolutionParent(args.importer, options.projectDir);
+  if (args.path.startsWith("@ecopages/")) {
+    const packageName = getPackageNameFromSpecifier(args.path);
+    const isBareWorkspacePackage = args.path === packageName;
+    const installedResolvedPath = resolveInstalledPackageTarget(args.path, resolveParent);
+    if (installedResolvedPath) {
+      return { path: installedResolvedPath };
+    }
+    if (!isBareWorkspacePackage) {
+      const resolvedSubpath = resolveSpecifier(args.path, resolveParent);
+      return { path: resolvedSubpath };
+    }
+    let resolvedPath2;
+    try {
+      resolvedPath2 = resolveFromCore(args.path);
+    } catch {
+      try {
+        resolvedPath2 = resolveSpecifier(args.path, resolveParent);
+      } catch {
+        const candidatePath = path.join(options.projectDir, "node_modules", packageName);
+        const candidatePackageJson = path.join(candidatePath, "package.json");
+        if (existsSync(candidatePackageJson)) {
+          ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, candidatePackageJson);
+          return { path: args.path, external: true };
+        }
+      }
+    }
+    if (!resolvedPath2) {
+      return void 0;
+    }
+    if (resolvedPath2.includes(`${path.sep}node_modules${path.sep}`)) {
+      ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, resolvedPath2);
+      return {
+        path: args.path,
+        external: true
+      };
+    }
+    return { path: resolvedPath2 };
+  }
+  const resolvedPath = resolveSpecifier(args.path, resolveParent);
+  ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, resolvedPath);
+  return {
+    path: args.path,
+    external: true
+  };
+}
+function createNodeBootstrapPlugin(options) {
+  const projectDir = path.resolve(options.projectDir);
+  return {
+    name: "node-bootstrap-plugin",
+    setup(build) {
+      build.onResolve({ filter: /^bun:/ }, (args) => {
+        throw new Error(getNodeUnsupportedBuiltinError(args.path, args.importer));
+      });
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (args) => {
+        const absolutePath = path.resolve(args.path);
+        const shouldRewriteImportMeta = shouldRewriteBootstrapSource(absolutePath, projectDir);
+        if (!shouldRewriteImportMeta) {
+          return void 0;
+        }
+        const originalContents = readFileSync(args.path, "utf8");
+        const contents = originalContents.replaceAll("import.meta.dirname", JSON.stringify(path.dirname(args.path))).replaceAll("import.meta.filename", JSON.stringify(args.path));
+        if (contents === originalContents) {
+          return void 0;
+        }
+        return {
+          contents,
+          loader: getBootstrapBuildLoaderForPath(args.path),
+          resolveDir: path.dirname(args.path)
+        };
+      });
+      build.onResolve({ filter: /^[@A-Za-z0-9][^:]*$/ }, (args) => {
+        return resolveNodeBootstrapDependency(args, options);
+      });
+    }
+  };
+}
+function createAppNodeBootstrapPlugin(appConfig) {
+  return createNodeBootstrapPlugin({
+    projectDir: appConfig.rootDir,
+    runtimeNodeModulesDir: getAppRuntimeNodeModulesDir(appConfig)
+  });
+}
+export {
+  createAppNodeBootstrapPlugin,
+  createNodeBootstrapPlugin,
+  getAppRuntimeNodeModulesDir,
+  getNodeUnsupportedBuiltinError,
+  resolveNodeBootstrapDependency
+};

package/src/services/module-loading/page-module-import.service.d.ts

@@ -0,0 +1,95 @@
+import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { SourceModuleLoaderFactory } from './module-loading-types.js';
+interface PageModuleImportBaseOptions {
+    filePath: string;
+    bypassCache?: boolean;
+    cacheScope?: string;
+    invalidationVersion?: number;
+}
+/**
+ * Options for imports that must pass through the Ecopages build pipeline.
+ *
+ * @remarks
+ * Callers should use build mode for framework-owned page modules and any other
+ * source that relies on Ecopages build resolution before runtime execution.
+ */
+export interface PageModuleBuildImportOptions extends PageModuleImportBaseOptions {
+    rootDir: string;
+    outdir: string;
+    buildExecutor?: BuildExecutor;
+    splitting?: boolean;
+    externalPackages?: boolean;
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
+    plugins?: EcoBuildPlugin[];
+    transpileErrorMessage?: (details: string) => string;
+    noOutputMessage?: (filePath: string) => string;
+}
+/**
+ * Minimal runtime dependencies required to load page modules.
+ *
+ * @remarks
+ * This service owns cache and runtime import policy. Hashing and build
+ * execution are injected so tests can provide explicit fakes without module
+ * interception.
+ */
+export interface PageModuleImportDependencies {
+    hashFile(filePath: string): string;
+    buildModule(options: Parameters<typeof build>[0], buildExecutor?: BuildExecutor): Promise<BuildResult>;
+    canLoadSourceModuleFromHost(filePath: string): boolean;
+    getHostModuleLoader: SourceModuleLoaderFactory;
+}
+/**
+ * Loads page-like modules through the Ecopages build pipeline.
+ *
+ * This service centralizes the shared build-first import strategy used by route
+ * scanning, page data loading, and request-time page inspection. In Node
+ * development it can still delegate compatible source imports to the active
+ * host loader, but the public contract remains one transpile-targeted module
+ * loading path.
+ *
+ * Keeping this logic in one place prevents subtle drift in cache-busting,
+ * transpilation settings, and error semantics across the different callers.
+ */
+export declare class PageModuleImportService {
+    private readonly dependencies;
+    private readonly importCache;
+    private developmentInvalidationVersion;
+    constructor(dependencies?: Partial<PageModuleImportDependencies>);
+    /**
+     * Clears the shared import cache used by framework-owned page-module loads.
+     */
+    clearImportCache(): void;
+    /**
+     * Invalidates all previously imported modules in development by clearing the
+     * import cache and incrementing the invalidation version included in cache keys.
+     *
+     * This forces all modules to be reloaded on the next import, even if their
+     * source content hasn't changed. This is necessary to ensure that changes to
+     * non-content aspects of modules (e.g. dependencies, transpilation output)
+     * are picked up during development.
+     */
+    invalidateDevelopmentGraph(): void;
+    /**
+     * Imports a page-like module from source.
+     *
+     * The caller controls the output directory and error wording so different
+     * subsystems can reuse the same loading mechanism while preserving their
+     * current diagnostics. Module identities stay stable for unchanged files and
+     * roll forward automatically when the source hash changes during watch mode.
+     *
+     * @typeParam T Expected module shape.
+     * @param options Runtime-specific import settings.
+     * @returns The loaded module.
+     */
+    importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T>;
+    private loadModule;
+}
+export {};