@ecopages/core 0.2.0-beta.37 → 0.2.0-beta.39

package/src/services/module-loading/collection-server-module-build.service.d.ts

@@ -0,0 +1,19 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type CollectionServerBuildArtifact = {
+    collectionName: string;
+    outputPath: string;
+    outputUrl: string;
+    sourcePaths: string[];
+    buildIdentity: string;
+};
+export declare function getCollectionServerBuildArtifact(appConfig: EcoPagesAppConfig, collectionName: string): CollectionServerBuildArtifact | undefined;
+export declare function clearCollectionServerBuildArtifacts(appConfig: EcoPagesAppConfig): void;
+/**
+ * Builds one generated collection server module as an independent server unit.
+ */
+export declare function buildCollectionServerModule(input: {
+    appConfig: EcoPagesAppConfig;
+    collectionName: string;
+    sourceFilePath: string;
+    ownedSourcePaths: readonly string[];
+}): Promise<CollectionServerBuildArtifact>;

package/src/services/module-loading/collection-server-module-build.service.js

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { build } from '../../build/build-adapter.js';
+import { createBuildRequestIdentity } from '../../build/runtime/build-request-identity.js';
+import { createServerBuildRequest } from '../../build/runtime/build-request-policy.js';
+import { recordCollectionBuild } from '../../diagnostics/request-pipeline-metrics.js';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.js';
+import { fileSystem } from '@ecopages/file-system';
+const artifactsByCollection = new WeakMap();
+function getArtifactMap(appConfig) {
+    let artifacts = artifactsByCollection.get(appConfig);
+    if (!artifacts) {
+        artifacts = new Map();
+        artifactsByCollection.set(appConfig, artifacts);
+    }
+    return artifacts;
+}
+export function getCollectionServerBuildArtifact(appConfig, collectionName) {
+    return getArtifactMap(appConfig).get(collectionName);
+}
+export function clearCollectionServerBuildArtifacts(appConfig) {
+    getArtifactMap(appConfig).clear();
+}
+function createCollectionBuildIdentity(buildRequestIdentity, sourceFilePath, ownedSourcePaths) {
+    const sourcePaths = [
+        ...new Set([sourceFilePath, ...ownedSourcePaths].map((sourcePath) => path.resolve(sourcePath))),
+    ].sort();
+    const sourceIdentity = sourcePaths
+        .map((sourcePath) => `${sourcePath}\0${fileSystem.exists(sourcePath) ? fileSystem.hash(sourcePath) : 'missing'}`)
+        .join('\0');
+    return createHash('sha256')
+        .update('collection-server-build-v2\0')
+        .update(buildRequestIdentity)
+        .update('\0')
+        .update(sourceIdentity)
+        .digest('hex')
+        .slice(0, 16);
+}
+/**
+ * Builds one generated collection server module as an independent server unit.
+ */
+export async function buildCollectionServerModule(input) {
+    const { appConfig, collectionName, sourceFilePath, ownedSourcePaths } = input;
+    const outdir = path.join(resolveInternalExecutionDir(appConfig), '.server-collections', collectionName);
+    const buildRequest = createServerBuildRequest(appConfig, {
+        profile: 'route-module',
+        entrypoints: [sourceFilePath],
+        outdir,
+        naming: '[name].[ext]',
+        splitting: false,
+        externalPackages: true,
+    });
+    const buildIdentity = createCollectionBuildIdentity(createBuildRequestIdentity(buildRequest), sourceFilePath, ownedSourcePaths);
+    const artifacts = getArtifactMap(appConfig);
+    const existing = artifacts.get(collectionName);
+    if (existing?.buildIdentity === buildIdentity) {
+        return existing;
+    }
+    const outputFileName = `${collectionName}-${buildIdentity}.mjs`;
+    const buildOptions = { ...buildRequest, naming: outputFileName.replace(/\.mjs$/u, '.[ext]') };
+    recordCollectionBuild();
+    const buildResult = await build(buildOptions);
+    if (!buildResult.success) {
+        const details = buildResult.logs.map((log) => log.message).join(' | ');
+        throw new Error(`Error building collection server module ${collectionName}: ${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(`No compiled output generated for collection server module: ${sourceFilePath}`);
+    }
+    const artifact = {
+        collectionName,
+        outputPath: compiledOutput,
+        outputUrl: pathToFileURL(compiledOutput).href,
+        sourcePaths: [...ownedSourcePaths, sourceFilePath],
+        buildIdentity,
+    };
+    artifacts.set(collectionName, artifact);
+    return artifact;
+}

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

@@ -1,12 +1,10 @@
-import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.js';
+import { build, type BuildExecutor, type BuildOptions, type BuildResult } from '../../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
 import type { EcoPagesAppConfig } from '../../types/internal-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.
@@ -21,6 +19,7 @@ export interface PageModuleBuildImportOptions extends PageModuleImportBaseOption
     buildExecutor?: BuildExecutor;
     splitting?: boolean;
     externalPackages?: boolean;
+    sourceTransforms?: BuildOptions['sourceTransforms'];
     jsx?: {
         development?: boolean;
         factory?: string;
@@ -64,20 +63,15 @@ export declare class PageModuleImportService {
     private readonly dependencies;
     private readonly dependencyHasher;
     private readonly importCache;
-    private developmentInvalidationVersion;
+    private developmentImportGeneration;
     constructor(appConfig?: EcoPagesAppConfig, 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.
+     * Clears in-memory import promises and dependency-hash memoization so the next
+     * import revalidates against current source and transform identity.
      */
     invalidateDevelopmentGraph(): void;
     /**

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

@@ -6,8 +6,8 @@ import { createServerBuildRequest } from '../../build/runtime/build-request-poli
 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 { recordPageModuleLoad } from '../../diagnostics/request-pipeline-metrics.js';
+import { createRouteModuleReuseIdentity, resolvePageModuleOutputFileName } from './route-module-build-manifest.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';
@@ -28,7 +28,7 @@ export class PageModuleImportService {
     dependencies;
     dependencyHasher;
     importCache = new Map();
-    developmentInvalidationVersion = 0;
+    developmentImportGeneration = 0;
     constructor(appConfig, dependencies) {
         this.appConfig = appConfig;
         this.dependencies = {
@@ -49,18 +49,13 @@ export class PageModuleImportService {
         this.importCache.clear();
     }
     /**
-     * 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.
+     * Clears in-memory import promises and dependency-hash memoization so the next
+     * import revalidates against current source and transform identity.
      */
     invalidateDevelopmentGraph() {
+        this.developmentImportGeneration += 1;
         this.clearImportCache();
         this.dependencyHasher.clearMemo();
-        this.developmentInvalidationVersion += 1;
     }
     /**
      * Imports a page-like module from source.
@@ -76,8 +71,6 @@ export class PageModuleImportService {
      */
     async importModule(options) {
         const { filePath } = options;
-        const invalidationVersion = options.invalidationVersion ?? this.developmentInvalidationVersion;
-        const { externalPackages, splitting } = options;
         const fileHash = this.dependencies.hashFile(filePath);
         const hostModuleLoader = typeof Bun === 'undefined' &&
             process.env.NODE_ENV === 'development' &&
@@ -85,63 +78,58 @@ export class PageModuleImportService {
             ? this.dependencies.getHostModuleLoader()
             : undefined;
         if (hostModuleLoader) {
-            const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, options.cacheScope);
-            return (await hostModuleLoader(sourceModuleUrl.href));
+            const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, this.developmentImportGeneration);
+            const loadedModule = (await hostModuleLoader(sourceModuleUrl.href));
+            recordPageModuleLoad('host-loader');
+            return loadedModule;
         }
-        if (options.bypassCache) {
-            this.developmentInvalidationVersion += 1;
-            return await this.loadModule({
+        if (!options.bypassCache) {
+            const runtime = typeof Bun !== 'undefined' ? 'bun' : 'node-build';
+            const cacheKey = [
+                runtime,
+                filePath,
+                createRouteModuleReuseIdentity(options, options.sourceTransforms),
+                fileHash,
+            ].join('::');
+            const cachedModule = this.importCache.get(cacheKey);
+            if (cachedModule) {
+                if (!cachedModule.dependencyHashes) {
+                    const loadedModule = (await cachedModule.promise);
+                    recordPageModuleLoad('import-cache-hit');
+                    return loadedModule;
+                }
+                if (this.dependencyHasher.matchesStoredHashes(cachedModule.dependencyHashes, filePath, fileHash)) {
+                    const loadedModule = (await cachedModule.promise);
+                    recordPageModuleLoad('import-cache-hit');
+                    return loadedModule;
+                }
+                this.importCache.delete(cacheKey);
+            }
+            const importPromise = this.loadModule({
                 ...options,
-                invalidationVersion: this.developmentInvalidationVersion,
                 fileHash,
+                importCacheKey: cacheKey,
             });
-        }
-        const runtime = typeof Bun !== 'undefined' ? 'bun' : 'node-build';
-        const cacheKey = [
-            runtime,
-            filePath,
-            options.rootDir,
-            path.resolve(options.outdir),
-            splitting ?? 'default',
-            externalPackages ?? 'default',
-            options.cacheScope ?? 'default',
-            createJsxCacheKey(options.jsx),
-            createPluginCacheKey(options.plugins),
-            fileHash,
-            invalidationVersion,
-        ].join('::');
-        const cachedModule = this.importCache.get(cacheKey);
-        if (cachedModule) {
-            if (!cachedModule.dependencyHashes) {
-                return (await cachedModule.promise);
+            this.importCache.set(cacheKey, { promise: importPromise });
+            try {
+                return await importPromise;
             }
-            if (this.dependencyHasher.matchesStoredHashes(cachedModule.dependencyHashes, filePath, fileHash)) {
-                return (await cachedModule.promise);
+            catch (error) {
+                this.importCache.delete(cacheKey);
+                throw error;
             }
-            this.importCache.delete(cacheKey);
         }
-        const importPromise = this.loadModule({
+        return await this.loadModule({
             ...options,
             fileHash,
-            importCacheKey: cacheKey,
         });
-        this.importCache.set(cacheKey, { promise: importPromise });
-        try {
-            return await importPromise;
-        }
-        catch (error) {
-            this.importCache.delete(cacheKey);
-            throw error;
-        }
     }
     async loadModule(options) {
-        const { filePath, invalidationVersion = this.developmentInvalidationVersion, cacheScope, fileHash, importCacheKey, } = options;
+        const { filePath, fileHash, importCacheKey } = options;
         const { rootDir, outdir, splitting, externalPackages, transpileErrorMessage = (details) => `Error transpiling page module: ${details}`, noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`, } = options;
         const outputFileName = resolvePageModuleOutputFileName({
             filePath,
             fileHash,
-            cacheScope,
-            invalidationVersion,
         });
         const outputNamingTemplate = outputFileName.replace(/\.mjs$/u, '.[ext]');
         const preferredOutputPath = path.join(outdir, outputFileName);
@@ -178,24 +166,26 @@ export class PageModuleImportService {
             externalPackages: buildOptions.externalPackages,
             jsx: buildOptions.jsx,
             plugins: buildOptions.plugins,
+            sourceTransforms: buildOptions.sourceTransforms,
             fileHash,
         };
         const routeModuleBuildCache = this.getRouteModuleBuildCache(outdir);
         const cachedBuild = routeModuleBuildCache.lookup(cacheBuildOptions);
         if (cachedBuild) {
-            return (await import(/* @vite-ignore */ pathToFileURL(cachedBuild.outputPath).href));
+            const loadedModule = (await import(/* @vite-ignore */ pathToFileURL(cachedBuild.outputPath).href));
+            recordPageModuleLoad('disk-cache-hit');
+            return loadedModule;
         }
-        if (!cacheScope &&
-            shouldBuildPagesUnifiedGraph() &&
-            this.appConfig &&
-            isPagesUnifiedGraphPage(filePath, this.appConfig)) {
+        if (shouldBuildPagesUnifiedGraph() && this.appConfig && isPagesUnifiedGraphPage(filePath, this.appConfig)) {
             const graphModule = await importPagesUnifiedGraphModule(this.appConfig, filePath);
             if (graphModule !== undefined) {
+                recordPageModuleLoad('unified-graph');
                 return graphModule;
             }
         }
         recordPageModuleBuildInvocation();
         const buildResult = await this.dependencies.buildModule(buildOptions, options.buildExecutor);
+        recordPageModuleLoad('cold-build', buildResult.outputs.length);
         if (!buildResult.success) {
             const details = buildResult.logs.map((log) => log.message).join(' | ');
             throw new Error(transpileErrorMessage(details));
@@ -220,10 +210,8 @@ export class PageModuleImportService {
             dependencyModulePaths,
         });
         const compiledOutputUrl = pathToFileURL(compiledOutput);
-        if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
-            compiledOutputUrl.searchParams.set('update', [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : undefined]
-                .filter((value) => value !== undefined)
-                .join('-'));
+        if (shouldAddRuntimeUpdateQuery()) {
+            compiledOutputUrl.searchParams.set('update', `${fileHash}-${this.developmentImportGeneration}`);
         }
         return (await import(/* @vite-ignore */ compiledOutputUrl.href));
     }
@@ -231,18 +219,13 @@ export class PageModuleImportService {
         return getSharedRouteModuleBuildCache(outdir, this.appConfig);
     }
 }
-function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheScope) {
+function createRuntimeModuleUrl(filePath, fileHash, developmentImportGeneration) {
     const moduleUrl = pathToFileURL(filePath);
-    if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
-        moduleUrl.searchParams.set('update', [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : undefined]
-            .filter((value) => value !== undefined)
-            .join('-'));
+    if (shouldAddRuntimeUpdateQuery()) {
+        moduleUrl.searchParams.set('update', `${fileHash}-${developmentImportGeneration}`);
     }
     return moduleUrl;
 }
-function shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope) {
-    return process.env.NODE_ENV === 'development' || invalidationVersion > 0 || !!cacheScope;
-}
-function sanitizeCacheScope(cacheScope) {
-    return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, '-');
+function shouldAddRuntimeUpdateQuery() {
+    return process.env.NODE_ENV === 'development';
 }

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

@@ -28,10 +28,10 @@ export class RouteModuleBuildCache {
             return undefined;
         }
         const manifest = this.loadManifest();
-        if (manifest.invalidationVersion !== this.dependencies.getCorePackageVersion()) {
+        if (manifest.corePackageVersion !== this.dependencies.getCorePackageVersion()) {
             return undefined;
         }
-        const buildKey = createPersistedRouteModuleBuildKey(options);
+        const buildKey = createPersistedRouteModuleBuildKey(options, options.sourceTransforms);
         const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
         const entry = manifest.entries[cacheFilePath];
         if (!entry || entry.sourceHash !== options.fileHash || entry.buildKey !== buildKey) {
@@ -60,12 +60,12 @@ export class RouteModuleBuildCache {
         dependencyHashes[cacheFilePath] = options.fileHash;
         const manifest = this.loadManifest();
         const existingEntry = manifest.entries[cacheFilePath];
-        manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+        manifest.corePackageVersion = this.dependencies.getCorePackageVersion();
         manifest.entries[cacheFilePath] = {
             sourceHash: options.fileHash,
             outputPath: options.outputPath,
             builtAt: Date.now(),
-            buildKey: createPersistedRouteModuleBuildKey(options),
+            buildKey: createPersistedRouteModuleBuildKey(options, options.sourceTransforms),
             dependencyHashes,
             renderedOutputs: existingEntry?.renderedOutputs,
         };
@@ -87,7 +87,7 @@ export class RouteModuleBuildCache {
             return;
         }
         const manifest = this.loadManifest();
-        manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+        manifest.corePackageVersion = this.dependencies.getCorePackageVersion();
         manifest.configHash = context.configHash;
         manifest.buildInputsFingerprint = context.buildInputsFingerprint;
         this.persistManifest(manifest);
@@ -140,7 +140,7 @@ export class RouteModuleBuildCache {
         const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
         const manifest = this.loadManifest();
         const existingEntry = manifest.entries[cacheFilePath];
-        manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+        manifest.corePackageVersion = this.dependencies.getCorePackageVersion();
         manifest.configHash = options.context.configHash;
         manifest.buildInputsFingerprint = options.context.buildInputsFingerprint;
         manifest.entries[cacheFilePath] = {

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

@@ -1,3 +1,4 @@
+import type { BuildOptions } from '../../build/contracts/build-contracts.js';
 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';
@@ -19,7 +20,7 @@ export interface RouteModuleStaticRenderCacheEntry {
 }
 /** On-disk manifest describing all cached route-module builds for one server outdir. */
 export interface RouteModuleBuildCacheManifest {
-    invalidationVersion: string;
+    corePackageVersion: string;
     configHash?: string;
     buildInputsFingerprint?: string;
     entries: Record<string, RouteModuleBuildCacheEntry>;
@@ -38,17 +39,19 @@ export type RouteModuleBuildCacheManifestReader = (manifestPath: string) => Rout
 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. */
+/**
+ * Returns whether route-module disk caching should run for the current import.
+ */
 export declare function shouldPersistRouteModuleBuildCache(options: PageModuleBuildImportOptions): boolean;
+/** Canonical reuse identity for route-module memory and disk caches. */
+export declare function createRouteModuleReuseIdentity(options: PageModuleBuildImportOptions, sourceTransforms?: BuildOptions['sourceTransforms']): string;
 /** 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 createPersistedRouteModuleBuildKey(options: PageModuleBuildImportOptions, sourceTransforms?: BuildOptions['sourceTransforms']): string;
 export declare function createEmptyRouteModuleBuildCacheManifest(): RouteModuleBuildCacheManifest;
 export declare function readRouteModuleBuildCacheManifest(manifestPath: string): RouteModuleBuildCacheManifest | undefined;
 export declare function writeRouteModuleBuildCacheManifest(manifestPath: string, manifest: RouteModuleBuildCacheManifest): void;

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

@@ -1,39 +1,23 @@
 import path from 'node:path';
 import { readProductionCacheManifest, writeProductionCacheManifest } from '../../build/cache/production-build-cache.js';
-import { createJsxCacheKey, createPluginCacheKey, getCorePackageVersion } from '../../build/cache/cache-keys.js';
+import { createJsxCacheKey, createPluginCacheKey, createSourceTransformCacheKey, getCorePackageVersion, } from '../../build/cache/cache-keys.js';
 export { createJsxCacheKey, createPluginCacheKey, getCorePackageVersion, hashPluginSetup, } from '../../build/cache/cache-keys.js';
 export { ROUTE_MODULE_BUILD_CACHE_FILENAME } from '../../build/cache/cache-constants.js';
 /** Normalizes filesystem paths used as manifest keys and build-key inputs. */
 export function normalizeRouteModuleCachePath(filePath) {
     return path.resolve(filePath);
 }
-/** Returns whether route-module disk caching should run for the current import. */
+/**
+ * Returns whether route-module disk caching should run for the current import.
+ */
 export function shouldPersistRouteModuleBuildCache(options) {
-    if (process.env.NODE_ENV !== 'production') {
+    if (process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'development') {
         return false;
     }
-    if (options.bypassCache) {
-        return false;
-    }
-    if ((options.invalidationVersion ?? 0) > 0) {
-        return false;
-    }
-    if (options.cacheScope) {
-        return false;
-    }
-    return true;
-}
-/** Derives the deterministic on-disk filename for one transpiled route module. */
-export function resolvePageModuleOutputFileName(options) {
-    const fileBaseName = path.basename(options.filePath, path.extname(options.filePath));
-    const cacheScopeSuffix = options.cacheScope ? `-${sanitizeCacheScope(options.cacheScope)}` : '';
-    const invalidationSuffix = shouldVersionBuildOutputPath(options.invalidationVersion ?? 0)
-        ? `-v${options.invalidationVersion}`
-        : '';
-    return `${fileBaseName}-${options.fileHash}${cacheScopeSuffix}${invalidationSuffix}.mjs`;
+    return !options.bypassCache;
 }
-/** Builds the cache key for persisted production route-module builds. */
-export function createPersistedRouteModuleBuildKey(options) {
+/** Canonical reuse identity for route-module memory and disk caches. */
+export function createRouteModuleReuseIdentity(options, sourceTransforms) {
     return [
         path.resolve(options.rootDir),
         path.resolve(options.outdir),
@@ -41,11 +25,21 @@ export function createPersistedRouteModuleBuildKey(options) {
         options.externalPackages ?? 'default',
         createJsxCacheKey(options.jsx),
         createPluginCacheKey(options.plugins),
+        createSourceTransformCacheKey(sourceTransforms),
     ].join('::');
 }
+/** Derives the deterministic on-disk filename for one transpiled route module. */
+export function resolvePageModuleOutputFileName(options) {
+    const fileBaseName = path.basename(options.filePath, path.extname(options.filePath));
+    return `${fileBaseName}-${options.fileHash}.mjs`;
+}
+/** Builds the cache key for persisted production route-module builds. */
+export function createPersistedRouteModuleBuildKey(options, sourceTransforms) {
+    return createRouteModuleReuseIdentity(options, sourceTransforms);
+}
 export function createEmptyRouteModuleBuildCacheManifest() {
     return {
-        invalidationVersion: getCorePackageVersion(),
+        corePackageVersion: getCorePackageVersion(),
         entries: {},
     };
 }
@@ -55,7 +49,7 @@ export function readRouteModuleBuildCacheManifest(manifestPath) {
         return undefined;
     }
     return {
-        invalidationVersion: parsed.invalidationVersion ?? '',
+        corePackageVersion: parsed.corePackageVersion ?? parsed.invalidationVersion ?? '',
         configHash: parsed.configHash,
         buildInputsFingerprint: parsed.buildInputsFingerprint,
         entries: parsed.entries,
@@ -64,9 +58,3 @@ export function readRouteModuleBuildCacheManifest(manifestPath) {
 export function writeRouteModuleBuildCacheManifest(manifestPath, manifest) {
     writeProductionCacheManifest(manifestPath, manifest);
 }
-function shouldVersionBuildOutputPath(invalidationVersion) {
-    return typeof Bun !== 'undefined' && invalidationVersion > 0;
-}
-function sanitizeCacheScope(cacheScope) {
-    return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, '-');
-}

package/src/services/module-loading/server-module-transpiler.service.d.ts

@@ -18,7 +18,6 @@ export type ServerModuleTranspilerBootstrapArgs = {
     getBuildExecutor?: () => BuildExecutor | undefined;
     canLoadSourceModuleFromHost?: (filePath: string) => boolean;
     getHostModuleLoader?: SourceModuleLoaderFactory;
-    getInvalidationVersion?: () => number;
     invalidateModules?: (changedFiles?: string[]) => void;
     pageModuleImportService?: ServerModuleImportDependency;
     /** Factory evaluated on each importModule call to produce plugins applied to every load. */
@@ -35,7 +34,6 @@ export declare class ServerModuleTranspiler {
     private readonly pageModuleImportService;
     private readonly getRootDir;
     private readonly getBuildExecutor;
-    private readonly getInvalidationVersion;
     private readonly invalidateModules;
     private readonly getDefaultPlugins;
     /**

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

@@ -10,7 +10,6 @@ export class ServerModuleTranspiler {
     pageModuleImportService;
     getRootDir;
     getBuildExecutor;
-    getInvalidationVersion;
     invalidateModules;
     getDefaultPlugins;
     /**
@@ -26,7 +25,6 @@ export class ServerModuleTranspiler {
                 });
         this.getRootDir = () => args.rootDir;
         this.getBuildExecutor = args.getBuildExecutor ?? (() => undefined);
-        this.getInvalidationVersion = () => args.getInvalidationVersion?.();
         this.getDefaultPlugins = args.getDefaultPlugins ?? (() => []);
         this.invalidateModules = (changedFiles) => {
             if (args.invalidateModules) {
@@ -48,7 +46,6 @@ export class ServerModuleTranspiler {
             ...(mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {}),
             rootDir: this.getRootDir(),
             buildExecutor: this.getBuildExecutor(),
-            invalidationVersion: this.getInvalidationVersion(),
         });
     }
     /**

package/src/static-site-generator/production-page-browser-graph-prebuild.d.ts

@@ -1,5 +1,10 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { PageParams } from '../types/public-types.js';
 import type { PageRendererResolver } from '../route-renderer/route-renderer.js';
+export type ProductionPageBrowserGraphRouteInstance = {
+    routeFile: string;
+    params?: PageParams;
+};
 /**
  * Returns whether production static export should warm Page Browser Graphs before rendering.
  *
@@ -17,12 +22,11 @@ export declare function shouldPrebuildProductionPageBrowserGraphs(): boolean;
  */
 export declare function clearProductionPageBrowserGraphSession(appConfig: EcoPagesAppConfig): void;
 /**
- * Warms production Page Browser Graphs for the supplied static route files.
+ * Warms production Page Browser Graphs for the supplied static route instances.
  *
  * @remarks
- * Deduplicates and lexicographically sorts absolute route paths, then calls
- * each integration renderer's `prebuildProductionPageBrowserGraph` sequentially
- * (activates integration runtime, then resolves into
- * `page-browser-graph-session`). Does not persist a disk manifest.
+ * Deduplicates route file + params pairs, then calls each integration renderer's
+ * `prebuildProductionPageBrowserGraph` sequentially (activates integration runtime,
+ * then resolves into `page-browser-graph-session`). Does not persist a disk manifest.
  */
-export declare function prebuildProductionPageBrowserGraphs(routeFiles: readonly string[], routeRendererFactory: PageRendererResolver): Promise<void>;
+export declare function prebuildProductionPageBrowserGraphs(routeInstances: readonly ProductionPageBrowserGraphRouteInstance[], routeRendererFactory: PageRendererResolver): Promise<void>;