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

package/src/services/module-loading/page-module-import.service.js

@@ -2,19 +2,40 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { fileSystem } from "@ecopages/file-system";
 import { build } from "../../build/build-adapter.js";
-import { normalizeNodeRuntimeBuildOutputFile } from "../../build/runtime-build-output-normalizer.js";
+import { createServerBuildRequest } from "../../build/runtime/build-request-policy.js";
+import { resolveBuildProfileOptions } from "../../build/runtime/build-profile-options.js";
+import {
+  importPagesUnifiedGraphModule,
+  isPagesUnifiedGraphPage,
+  shouldBuildPagesUnifiedGraph
+} from "../../build/cache/pages-unified-graph-build.js";
+import { recordPageModuleBuildInvocation } from "../../build/rolldown/rolldown-build-invocation-metrics.js";
+import { resolvePageModuleOutputFileName } from "./route-module-build-cache.js";
+import { createPluginCacheKey, createJsxCacheKey } from "../../build/cache/cache-keys.js";
+import { getSharedRouteModuleBuildCache } from "./route-module-build-cache-registry.js";
+import {
+  RouteModuleDependencyHasher,
+  resolveRouteModuleDependencyPaths
+} from "./route-module-dependency-hasher.js";
 import { supportsSourceModuleLoading } from "./source-module-support.js";
 class PageModuleImportService {
+  appConfig;
   dependencies;
+  dependencyHasher;
   importCache = /* @__PURE__ */ new Map();
   developmentInvalidationVersion = 0;
-  constructor(dependencies) {
+  constructor(appConfig, dependencies) {
+    this.appConfig = appConfig;
     this.dependencies = {
       hashFile: dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath)),
       buildModule: dependencies?.buildModule ?? ((options, buildExecutor) => build(options, buildExecutor)),
       canLoadSourceModuleFromHost: dependencies?.canLoadSourceModuleFromHost ?? supportsSourceModuleLoading,
       getHostModuleLoader: dependencies?.getHostModuleLoader ?? (() => void 0)
     };
+    this.dependencyHasher = new RouteModuleDependencyHasher({
+      hashFile: (filePath) => this.dependencies.hashFile(filePath),
+      exists: (filePath) => fileSystem.exists(filePath)
+    });
   }
   /**
    * Clears the shared import cache used by framework-owned page-module loads.
@@ -33,6 +54,7 @@ class PageModuleImportService {
    */
   invalidateDevelopmentGraph() {
     this.clearImportCache();
+    this.dependencyHasher.clearMemo();
     this.developmentInvalidationVersion += 1;
   }
   /**
@@ -70,6 +92,7 @@ class PageModuleImportService {
       runtime,
       filePath,
       options.rootDir,
+      path.resolve(options.outdir),
       splitting ?? "default",
       externalPackages ?? "default",
       options.cacheScope ?? "default",
@@ -80,13 +103,20 @@ class PageModuleImportService {
     ].join("::");
     const cachedModule = this.importCache.get(cacheKey);
     if (cachedModule) {
-      return await cachedModule;
+      if (!cachedModule.dependencyHashes) {
+        return await cachedModule.promise;
+      }
+      if (this.dependencyHasher.matchesStoredHashes(cachedModule.dependencyHashes, filePath, fileHash)) {
+        return await cachedModule.promise;
+      }
+      this.importCache.delete(cacheKey);
     }
     const importPromise = this.loadModule({
       ...options,
-      fileHash
+      fileHash,
+      importCacheKey: cacheKey
     });
-    this.importCache.set(cacheKey, importPromise);
+    this.importCache.set(cacheKey, { promise: importPromise });
     try {
       return await importPromise;
     } catch (error) {
@@ -95,7 +125,13 @@ class PageModuleImportService {
     }
   }
   async loadModule(options) {
-    const { filePath, invalidationVersion = this.developmentInvalidationVersion, cacheScope, fileHash } = options;
+    const {
+      filePath,
+      invalidationVersion = this.developmentInvalidationVersion,
+      cacheScope,
+      fileHash,
+      importCacheKey
+    } = options;
     const {
       rootDir,
       outdir,
@@ -104,39 +140,85 @@ class PageModuleImportService {
       transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
       noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`
     } = options;
-    const fileBaseName = path.basename(filePath, path.extname(filePath));
-    const cacheScopeSuffix = cacheScope ? `-${sanitizeCacheScope(cacheScope)}` : "";
-    const invalidationSuffix = shouldVersionBuildOutputPath(invalidationVersion) ? `-v${invalidationVersion}` : "";
-    const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${invalidationSuffix}.mjs`;
-    const outputNamingTemplate = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${invalidationSuffix}.[ext]`;
-    const buildResult = await this.dependencies.buildModule(
-      {
+    const outputFileName = resolvePageModuleOutputFileName({
+      filePath,
+      fileHash,
+      cacheScope,
+      invalidationVersion
+    });
+    const outputNamingTemplate = outputFileName.replace(/\.mjs$/u, ".[ext]");
+    const preferredOutputPath = path.join(outdir, outputFileName);
+    const buildOptions = this.appConfig ? createServerBuildRequest(this.appConfig, {
+      profile: "route-module",
+      entrypoints: [filePath],
+      outdir,
+      naming: outputNamingTemplate,
+      splitting: splitting ?? true,
+      jsx: options.jsx,
+      plugins: options.plugins,
+      root: rootDir,
+      ...externalPackages !== void 0 ? { externalPackages } : {}
+    }) : {
+      ...resolveBuildProfileOptions("route-module", { rootDir }, {
         entrypoints: [filePath],
-        root: rootDir,
         outdir,
-        target: "es2022",
-        format: "esm",
-        sourcemap: "none",
-        splitting: splitting ?? true,
-        minify: false,
         naming: outputNamingTemplate,
-        externalPackages: true,
+        splitting: splitting ?? true,
         jsx: options.jsx,
         plugins: options.plugins,
         ...externalPackages !== void 0 ? { externalPackages } : {}
-      },
-      options.buildExecutor
-    );
+      }),
+      root: rootDir,
+      entrypoints: [filePath]
+    };
+    const cacheBuildOptions = {
+      ...options,
+      rootDir: buildOptions.root ?? rootDir,
+      outdir: buildOptions.outdir ?? outdir,
+      splitting: buildOptions.splitting,
+      externalPackages: buildOptions.externalPackages,
+      jsx: buildOptions.jsx,
+      plugins: buildOptions.plugins,
+      fileHash
+    };
+    const routeModuleBuildCache = this.getRouteModuleBuildCache(outdir);
+    const cachedBuild = routeModuleBuildCache.lookup(cacheBuildOptions);
+    if (cachedBuild) {
+      return await import(
+        /* @vite-ignore */
+        pathToFileURL(cachedBuild.outputPath).href
+      );
+    }
+    if (!cacheScope && shouldBuildPagesUnifiedGraph() && this.appConfig && isPagesUnifiedGraphPage(filePath, this.appConfig)) {
+      const graphModule = await importPagesUnifiedGraphModule(this.appConfig, filePath);
+      if (graphModule !== void 0) {
+        return graphModule;
+      }
+    }
+    recordPageModuleBuildInvocation();
+    const buildResult = await this.dependencies.buildModule(buildOptions, options.buildExecutor);
     if (!buildResult.success) {
       const details = buildResult.logs.map((log) => log.message).join(" | ");
       throw new Error(transpileErrorMessage(details));
     }
-    const preferredOutputPath = path.join(outdir, outputFileName);
     const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => /\.(?:[cm]?js)$/u.test(output.path))?.path;
     if (!compiledOutput) {
       throw new Error(noOutputMessage(filePath));
     }
-    normalizeNodeRuntimeBuildOutputFile(compiledOutput, rootDir);
+    const dependencyModulePaths = resolveRouteModuleDependencyPaths(buildResult, filePath, rootDir);
+    const dependencyHashes = this.dependencyHasher.createDependencyHashes(dependencyModulePaths);
+    dependencyHashes[path.normalize(filePath)] = fileHash;
+    if (importCacheKey) {
+      const cacheEntry = this.importCache.get(importCacheKey);
+      if (cacheEntry) {
+        cacheEntry.dependencyHashes = dependencyHashes;
+      }
+    }
+    routeModuleBuildCache.recordBuild({
+      ...cacheBuildOptions,
+      outputPath: compiledOutput,
+      dependencyModulePaths
+    });
     const compiledOutputUrl = pathToFileURL(compiledOutput);
     if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
       compiledOutputUrl.searchParams.set(
@@ -149,6 +231,9 @@ class PageModuleImportService {
       compiledOutputUrl.href
     );
   }
+  getRouteModuleBuildCache(outdir) {
+    return getSharedRouteModuleBuildCache(outdir, this.appConfig);
+  }
 }
 function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheScope) {
   const moduleUrl = pathToFileURL(filePath);
@@ -163,31 +248,9 @@ function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheSc
 function shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope) {
   return process.env.NODE_ENV === "development" || invalidationVersion > 0 || !!cacheScope;
 }
-function shouldVersionBuildOutputPath(invalidationVersion) {
-  return typeof Bun !== "undefined" && invalidationVersion > 0;
-}
 function sanitizeCacheScope(cacheScope) {
   return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
 }
-function createJsxCacheKey(jsx) {
-  if (!jsx) {
-    return "jsx:default";
-  }
-  return JSON.stringify({
-    development: jsx.development ?? false,
-    factory: jsx.factory ?? null,
-    fragment: jsx.fragment ?? null,
-    importSource: jsx.importSource ?? null,
-    runtime: jsx.runtime ?? null,
-    sideEffects: jsx.sideEffects ?? null
-  });
-}
-function createPluginCacheKey(plugins) {
-  if (!plugins || plugins.length === 0) {
-    return "plugins:default";
-  }
-  return `plugins:${plugins.map((plugin) => plugin.name).join(",")}`;
-}
 export {
   PageModuleImportService
 };

package/src/services/module-loading/route-module-build-cache-registry.d.ts

@@ -0,0 +1,24 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { RouteModuleBuildCache } from './route-module-build-cache.store.js';
+/**
+ * Returns the outdir whose transpile cache backs incremental static generation.
+ *
+ * @remarks
+ * Static pages render through `.eco/.server-modules`. The manifest there carries
+ * import-graph hashes from transpile, so static-render reuse must read the same
+ * directory rather than `.server-route-modules`, which only serves route-registry
+ * scanning.
+ */
+export declare function getServerModuleBuildCacheOutdir(appConfig: EcoPagesAppConfig): string;
+/**
+ * @deprecated Use {@link getServerModuleBuildCacheOutdir}.
+ */
+export declare const getRouteModuleBuildCacheOutdir: typeof getServerModuleBuildCacheOutdir;
+/**
+ * Returns the shared production build cache for one server-module outdir.
+ *
+ * @remarks
+ * One app-scoped instance prevents manifest drift between page imports and static
+ * generation during the same build process.
+ */
+export declare function getSharedRouteModuleBuildCache(outdir: string, appConfig?: EcoPagesAppConfig): RouteModuleBuildCache;

package/src/services/module-loading/route-module-build-cache-registry.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
+import { RouteModuleBuildCache } from "./route-module-build-cache.store.js";
+function getServerModuleBuildCacheOutdir(appConfig) {
+  return path.join(resolveInternalExecutionDir(appConfig), ".server-modules");
+}
+const getRouteModuleBuildCacheOutdir = getServerModuleBuildCacheOutdir;
+function getRouteModuleBuildCacheMap(appConfig) {
+  const existing = appConfig.runtime?.routeModuleBuildCaches;
+  if (existing) {
+    return existing;
+  }
+  const routeModuleBuildCaches = /* @__PURE__ */ new Map();
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    routeModuleBuildCaches
+  };
+  return routeModuleBuildCaches;
+}
+function getSharedRouteModuleBuildCache(outdir, appConfig) {
+  if (!appConfig) {
+    return new RouteModuleBuildCache(outdir);
+  }
+  const caches = getRouteModuleBuildCacheMap(appConfig);
+  const existingCache = caches.get(outdir);
+  if (existingCache) {
+    return existingCache;
+  }
+  const routeModuleBuildCache = new RouteModuleBuildCache(outdir);
+  caches.set(outdir, routeModuleBuildCache);
+  return routeModuleBuildCache;
+}
+export {
+  getRouteModuleBuildCacheOutdir,
+  getServerModuleBuildCacheOutdir,
+  getSharedRouteModuleBuildCache
+};

package/src/services/module-loading/route-module-build-cache.d.ts

@@ -0,0 +1,4 @@
+export type { RouteModuleDependencyHashes } from './route-module-dependency-hasher.js';
+export { ROUTE_MODULE_BUILD_CACHE_FILENAME, createEmptyRouteModuleBuildCacheManifest, createPersistedRouteModuleBuildKey, createPluginCacheKey, createJsxCacheKey, hashPluginSetup, getCorePackageVersion, normalizeRouteModuleCachePath, readRouteModuleBuildCacheManifest, resolvePageModuleOutputFileName, shouldPersistRouteModuleBuildCache, writeRouteModuleBuildCacheManifest, type RouteModuleBuildCacheEntry, type RouteModuleBuildCacheLookup, type RouteModuleBuildCacheManifest, type RouteModuleStaticRenderCacheContext, type RouteModuleStaticRenderCacheEntry, } from './route-module-build-manifest.js';
+export { RouteModuleBuildCache } from './route-module-build-cache.store.js';
+export { getRouteModuleBuildCacheOutdir, getServerModuleBuildCacheOutdir, getSharedRouteModuleBuildCache, } from './route-module-build-cache-registry.js';

package/src/services/module-loading/route-module-build-cache.js

@@ -0,0 +1,38 @@
+import {
+  ROUTE_MODULE_BUILD_CACHE_FILENAME,
+  createEmptyRouteModuleBuildCacheManifest,
+  createPersistedRouteModuleBuildKey,
+  createPluginCacheKey,
+  createJsxCacheKey,
+  hashPluginSetup,
+  getCorePackageVersion,
+  normalizeRouteModuleCachePath,
+  readRouteModuleBuildCacheManifest,
+  resolvePageModuleOutputFileName,
+  shouldPersistRouteModuleBuildCache,
+  writeRouteModuleBuildCacheManifest
+} from "./route-module-build-manifest.js";
+import { RouteModuleBuildCache } from "./route-module-build-cache.store.js";
+import {
+  getRouteModuleBuildCacheOutdir,
+  getServerModuleBuildCacheOutdir,
+  getSharedRouteModuleBuildCache
+} from "./route-module-build-cache-registry.js";
+export {
+  ROUTE_MODULE_BUILD_CACHE_FILENAME,
+  RouteModuleBuildCache,
+  createEmptyRouteModuleBuildCacheManifest,
+  createJsxCacheKey,
+  createPersistedRouteModuleBuildKey,
+  createPluginCacheKey,
+  getCorePackageVersion,
+  getRouteModuleBuildCacheOutdir,
+  getServerModuleBuildCacheOutdir,
+  getSharedRouteModuleBuildCache,
+  hashPluginSetup,
+  normalizeRouteModuleCachePath,
+  readRouteModuleBuildCacheManifest,
+  resolvePageModuleOutputFileName,
+  shouldPersistRouteModuleBuildCache,
+  writeRouteModuleBuildCacheManifest
+};

package/src/services/module-loading/route-module-build-cache.store.d.ts

@@ -0,0 +1,57 @@
+import type { PageModuleBuildImportOptions } from './page-module-import.service.js';
+import { RouteModuleDependencyHasher, type RouteModuleDependencyHashes } from './route-module-dependency-hasher.js';
+import { type RouteModuleBuildCacheLookup, type RouteModuleBuildCacheManifest, type RouteModuleStaticRenderCacheContext } from './route-module-build-manifest.js';
+export type { RouteModuleDependencyHashes };
+type RouteModuleBuildCacheDependencies = {
+    readManifest: (manifestPath: string) => RouteModuleBuildCacheManifest | undefined;
+    writeManifest: (manifestPath: string, manifest: RouteModuleBuildCacheManifest) => void;
+    exists: (filePath: string) => boolean;
+    getCorePackageVersion: () => string;
+    createDependencyHasher: () => RouteModuleDependencyHasher;
+};
+/**
+ * Persists route-module transpile and static-render metadata under one server outdir.
+ */
+export declare class RouteModuleBuildCache {
+    private readonly manifestPath;
+    private readonly dependencies;
+    private readonly dependencyHasher;
+    private manifest;
+    private manifestLoaded;
+    constructor(outdir: string, dependencies?: Partial<RouteModuleBuildCacheDependencies>);
+    lookup(options: PageModuleBuildImportOptions & {
+        fileHash: string;
+    }): RouteModuleBuildCacheLookup | undefined;
+    recordBuild(options: PageModuleBuildImportOptions & {
+        fileHash: string;
+        outputPath: string;
+        dependencyModulePaths?: readonly string[];
+    }): void;
+    isIncrementalStaticGenerationAvailable(context: RouteModuleStaticRenderCacheContext): boolean;
+    ensureIncrementalStaticGenerationContext(context: RouteModuleStaticRenderCacheContext): void;
+    canReuseStaticRender(options: {
+        sourceFile: string;
+        pathname: string;
+        renderedOutputPath: string;
+        context: RouteModuleStaticRenderCacheContext;
+        force?: boolean;
+    }): boolean;
+    lookupStaticRender(options: {
+        filePath: string;
+        pathname: string;
+        sourceHash: string;
+        renderedOutputPath: string;
+        context: RouteModuleStaticRenderCacheContext;
+    }): boolean;
+    recordStaticRender(options: {
+        filePath: string;
+        pathname: string;
+        sourceHash: string;
+        renderedOutputPath: string;
+        context: RouteModuleStaticRenderCacheContext;
+    }): void;
+    resetMemory(): void;
+    pruneStaleRenderedOutputs(activePathnames: ReadonlySet<string>): string[];
+    private loadManifest;
+    private persistManifest;
+}

package/src/services/module-loading/route-module-build-cache.store.js

@@ -0,0 +1,207 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { RouteModuleDependencyHasher } from "./route-module-dependency-hasher.js";
+import {
+  ROUTE_MODULE_BUILD_CACHE_FILENAME,
+  createEmptyRouteModuleBuildCacheManifest,
+  createPersistedRouteModuleBuildKey,
+  getCorePackageVersion,
+  normalizeRouteModuleCachePath,
+  readRouteModuleBuildCacheManifest,
+  shouldPersistRouteModuleBuildCache,
+  writeRouteModuleBuildCacheManifest
+} from "./route-module-build-manifest.js";
+import {
+  isProductionCacheManifestCurrent,
+  matchesProductionCacheFingerprint
+} from "../../build/cache/production-build-cache.js";
+class RouteModuleBuildCache {
+  manifestPath;
+  dependencies;
+  dependencyHasher;
+  manifest;
+  manifestLoaded = false;
+  constructor(outdir, dependencies) {
+    this.manifestPath = path.join(outdir, ROUTE_MODULE_BUILD_CACHE_FILENAME);
+    this.dependencies = {
+      readManifest: dependencies?.readManifest ?? readRouteModuleBuildCacheManifest,
+      writeManifest: dependencies?.writeManifest ?? writeRouteModuleBuildCacheManifest,
+      exists: dependencies?.exists ?? ((filePath) => fileSystem.exists(filePath)),
+      getCorePackageVersion: dependencies?.getCorePackageVersion ?? getCorePackageVersion,
+      createDependencyHasher: dependencies?.createDependencyHasher ?? (() => new RouteModuleDependencyHasher())
+    };
+    this.dependencyHasher = this.dependencies.createDependencyHasher();
+  }
+  lookup(options) {
+    if (!shouldPersistRouteModuleBuildCache(options)) {
+      return void 0;
+    }
+    const manifest = this.loadManifest();
+    if (manifest.invalidationVersion !== this.dependencies.getCorePackageVersion()) {
+      return void 0;
+    }
+    const buildKey = createPersistedRouteModuleBuildKey(options);
+    const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
+    const entry = manifest.entries[cacheFilePath];
+    if (!entry || entry.sourceHash !== options.fileHash || entry.buildKey !== buildKey) {
+      return void 0;
+    }
+    if (!this.dependencyHasher.matchesStoredHashes(entry.dependencyHashes, cacheFilePath, options.fileHash)) {
+      return void 0;
+    }
+    const outputPath = path.isAbsolute(entry.outputPath) ? entry.outputPath : path.join(options.outdir, entry.outputPath);
+    if (!this.dependencies.exists(outputPath)) {
+      return void 0;
+    }
+    return { outputPath, entry };
+  }
+  recordBuild(options) {
+    if (!shouldPersistRouteModuleBuildCache(options)) {
+      return;
+    }
+    const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
+    const dependencyModulePaths = options.dependencyModulePaths && options.dependencyModulePaths.length > 0 ? options.dependencyModulePaths : [cacheFilePath];
+    const dependencyHashes = this.dependencyHasher.createDependencyHashes(dependencyModulePaths);
+    dependencyHashes[cacheFilePath] = options.fileHash;
+    const manifest = this.loadManifest();
+    const existingEntry = manifest.entries[cacheFilePath];
+    manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+    manifest.entries[cacheFilePath] = {
+      sourceHash: options.fileHash,
+      outputPath: options.outputPath,
+      builtAt: Date.now(),
+      buildKey: createPersistedRouteModuleBuildKey(options),
+      dependencyHashes,
+      renderedOutputs: existingEntry?.renderedOutputs
+    };
+    this.persistManifest(manifest);
+  }
+  isIncrementalStaticGenerationAvailable(context) {
+    if (process.env.NODE_ENV !== "production") {
+      return false;
+    }
+    const manifest = this.loadManifest();
+    if (!isProductionCacheManifestCurrent(manifest, this.dependencies.getCorePackageVersion())) {
+      return false;
+    }
+    return manifest.configHash === context.configHash && matchesProductionCacheFingerprint(manifest, context.buildInputsFingerprint);
+  }
+  ensureIncrementalStaticGenerationContext(context) {
+    if (process.env.NODE_ENV !== "production") {
+      return;
+    }
+    const manifest = this.loadManifest();
+    manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+    manifest.configHash = context.configHash;
+    manifest.buildInputsFingerprint = context.buildInputsFingerprint;
+    this.persistManifest(manifest);
+  }
+  canReuseStaticRender(options) {
+    if (options.force) {
+      return false;
+    }
+    if (!fileSystem.exists(options.sourceFile)) {
+      return false;
+    }
+    const sourceHash = fileSystem.hash(options.sourceFile);
+    return this.lookupStaticRender({
+      filePath: options.sourceFile,
+      pathname: options.pathname,
+      sourceHash,
+      renderedOutputPath: options.renderedOutputPath,
+      context: options.context
+    });
+  }
+  lookupStaticRender(options) {
+    if (!this.isIncrementalStaticGenerationAvailable(options.context)) {
+      return false;
+    }
+    const manifest = this.loadManifest();
+    const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
+    const entry = manifest.entries[cacheFilePath];
+    const renderedOutput = entry?.renderedOutputs?.[options.pathname];
+    if (!entry || !renderedOutput) {
+      return false;
+    }
+    if (entry.sourceHash !== options.sourceHash || renderedOutput.sourceHash !== options.sourceHash) {
+      return false;
+    }
+    if (!this.dependencyHasher.matchesStoredHashes(entry.dependencyHashes, cacheFilePath, options.sourceHash)) {
+      return false;
+    }
+    const cachedOutputPath = path.isAbsolute(renderedOutput.renderedOutputPath) ? renderedOutput.renderedOutputPath : path.resolve(renderedOutput.renderedOutputPath);
+    if (cachedOutputPath !== path.resolve(options.renderedOutputPath)) {
+      return false;
+    }
+    return this.dependencies.exists(cachedOutputPath);
+  }
+  recordStaticRender(options) {
+    if (process.env.NODE_ENV !== "production") {
+      return;
+    }
+    const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
+    const manifest = this.loadManifest();
+    const existingEntry = manifest.entries[cacheFilePath];
+    manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+    manifest.configHash = options.context.configHash;
+    manifest.buildInputsFingerprint = options.context.buildInputsFingerprint;
+    manifest.entries[cacheFilePath] = {
+      sourceHash: options.sourceHash,
+      outputPath: existingEntry?.outputPath ?? "",
+      builtAt: existingEntry?.builtAt ?? Date.now(),
+      buildKey: existingEntry?.buildKey ?? "",
+      dependencyHashes: existingEntry?.dependencyHashes,
+      renderedOutputs: {
+        ...existingEntry?.renderedOutputs ?? {},
+        [options.pathname]: {
+          renderedOutputPath: options.renderedOutputPath,
+          renderedAt: Date.now(),
+          sourceHash: options.sourceHash
+        }
+      }
+    };
+    this.persistManifest(manifest);
+  }
+  resetMemory() {
+    this.manifest = void 0;
+    this.manifestLoaded = false;
+  }
+  pruneStaleRenderedOutputs(activePathnames) {
+    if (process.env.NODE_ENV !== "production") {
+      return [];
+    }
+    const manifest = this.loadManifest();
+    const removedOutputPaths = [];
+    for (const entry of Object.values(manifest.entries)) {
+      if (!entry.renderedOutputs) {
+        continue;
+      }
+      for (const [pathname, renderedOutput] of Object.entries(entry.renderedOutputs)) {
+        if (activePathnames.has(pathname)) {
+          continue;
+        }
+        removedOutputPaths.push(renderedOutput.renderedOutputPath);
+        delete entry.renderedOutputs[pathname];
+      }
+    }
+    if (removedOutputPaths.length > 0) {
+      this.persistManifest(manifest);
+    }
+    return removedOutputPaths;
+  }
+  loadManifest() {
+    if (this.manifestLoaded) {
+      return this.manifest ?? createEmptyRouteModuleBuildCacheManifest();
+    }
+    this.manifestLoaded = true;
+    this.manifest = this.dependencies.readManifest(this.manifestPath) ?? createEmptyRouteModuleBuildCacheManifest();
+    return this.manifest;
+  }
+  persistManifest(manifest) {
+    this.manifest = manifest;
+    this.dependencies.writeManifest(this.manifestPath, manifest);
+  }
+}
+export {
+  RouteModuleBuildCache
+};

package/src/services/module-loading/route-module-build-manifest.d.ts

@@ -0,0 +1,54 @@
+import type { PageModuleBuildImportOptions } from './page-module-import.service.js';
+import type { RouteModuleDependencyHashes } from './route-module-dependency-hasher.js';
+export { createJsxCacheKey, createPluginCacheKey, getCorePackageVersion, hashPluginSetup, } from '../../build/cache/cache-keys.js';
+export { ROUTE_MODULE_BUILD_CACHE_FILENAME } from '../../build/cache/cache-constants.js';
+/** One persisted route-module build entry in {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}. */
+export interface RouteModuleBuildCacheEntry {
+    sourceHash: string;
+    outputPath: string;
+    builtAt: number;
+    buildKey: string;
+    dependencyHashes?: RouteModuleDependencyHashes;
+    renderedOutputs?: Record<string, RouteModuleStaticRenderCacheEntry>;
+}
+/** Metadata for one rendered static HTML artifact derived from a route module. */
+export interface RouteModuleStaticRenderCacheEntry {
+    renderedOutputPath: string;
+    renderedAt: number;
+    sourceHash: string;
+}
+/** On-disk manifest describing all cached route-module builds for one server outdir. */
+export interface RouteModuleBuildCacheManifest {
+    invalidationVersion: string;
+    configHash?: string;
+    buildInputsFingerprint?: string;
+    entries: Record<string, RouteModuleBuildCacheEntry>;
+}
+/** Successful route-module cache lookup result. */
+export interface RouteModuleBuildCacheLookup {
+    outputPath: string;
+    entry: RouteModuleBuildCacheEntry;
+}
+/** Inputs that must remain stable for incremental static HTML generation. */
+export interface RouteModuleStaticRenderCacheContext {
+    configHash: string;
+    buildInputsFingerprint: string;
+}
+export type RouteModuleBuildCacheManifestReader = (manifestPath: string) => RouteModuleBuildCacheManifest | undefined;
+export type RouteModuleBuildCacheManifestWriter = (manifestPath: string, manifest: RouteModuleBuildCacheManifest) => void;
+/** Normalizes filesystem paths used as manifest keys and build-key inputs. */
+export declare function normalizeRouteModuleCachePath(filePath: string): string;
+/** Returns whether route-module disk caching should run for the current import. */
+export declare function shouldPersistRouteModuleBuildCache(options: PageModuleBuildImportOptions): boolean;
+/** Derives the deterministic on-disk filename for one transpiled route module. */
+export declare function resolvePageModuleOutputFileName(options: {
+    filePath: string;
+    fileHash: string;
+    cacheScope?: string;
+    invalidationVersion?: number;
+}): string;
+/** Builds the cache key for persisted production route-module builds. */
+export declare function createPersistedRouteModuleBuildKey(options: PageModuleBuildImportOptions): string;
+export declare function createEmptyRouteModuleBuildCacheManifest(): RouteModuleBuildCacheManifest;
+export declare function readRouteModuleBuildCacheManifest(manifestPath: string): RouteModuleBuildCacheManifest | undefined;
+export declare function writeRouteModuleBuildCacheManifest(manifestPath: string, manifest: RouteModuleBuildCacheManifest): void;