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

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/static-site-generator.js

@@ -15,7 +15,7 @@ import { normalizePathname } from '../utils/path-pattern.js';
 export const STATIC_SITE_GENERATOR_ERRORS = {
     ROUTE_RENDERER_FACTORY_REQUIRED: 'RouteRendererFactory is required for render strategy',
     unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
-    missingIntegration: (routePath) => `View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page().`,
+    missingIntegration: (routePath) => `View at ${routePath} is missing component identity integration. Ensure it's defined with eco.page().`,
     noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`,
     dynamicRouteRequiresStaticPaths: (routePath) => `Dynamic route ${routePath} requires staticPaths to be defined on the view.`,
 };
@@ -430,7 +430,7 @@ export class StaticSiteGenerator {
         }
     }
     resolveExplicitViewSourceFile(view) {
-        const sourceFile = view.config?.__eco?.file;
+        const sourceFile = view.config?.identity?.file;
         if (!sourceFile) {
             return undefined;
         }

package/src/types/internal-types.d.ts

@@ -107,6 +107,10 @@ export type EcoPagesAppConfig = {
     sitemap: SitemapConfig;
     /** Additional paths to watch. Use this to monitor extra files. It is relative to the rootDir */
     additionalWatchPaths: string[];
+    /** Static paths to SSR-prewarm in development before user navigation. */
+    devPrewarmPaths?: string[];
+    /** Static paths to SSR-prewarm before the development server reports ready. */
+    devPrewarmBeforeReadyPaths?: string[];
     /**
      * @default { title: 'Ecopages', description: 'Ecopages' }
      */

package/src/types/public-types.d.ts

@@ -1,4 +1,5 @@
 import type { Readable } from 'node:stream';
+import type { ComponentIdentity } from '../eco/component-identity.js';
 import type { ApiResponseBuilder } from '../adapters/shared/http/api-response.js';
 import type { ForeignChildRuntime } from '../route-renderer/orchestration/foreign-child/component-render-context.js';
 import type { EcoPageComponent } from '../eco/eco.types.js';
@@ -339,7 +340,7 @@ export type EcoComponentDependencies = {
     /**
      * Child components whose assets and foreign-child graph are collected transitively.
      * Each entry must be an `eco.component()`, `eco.layout()`, or `eco.html()` result
-     * with plugin-injected `config.__eco` metadata.
+     * with bound component identity.
      */
     components?: EcoDeclaredComponent[];
 };
@@ -347,8 +348,8 @@ export type EcoComponentDependencies = {
  * Component returned from `eco.component()`, `eco.layout()`, or `eco.html()`.
  *
  * @remarks
- * Used for `dependencies.components` and eco factory return types. Plugin-injected
- * `config.__eco` is enforced at runtime via `isEcoDeclaredComponent()`, not by this alias.
+ * Used for `dependencies.components` and eco factory return types. Bound
+ * component identity is enforced at runtime via `isEcoDeclaredComponent()`, not by this alias.
  */
 export type EcoDeclaredComponent<P = any, R = any> = EcoComponent<P, R>;
 export type EcoPagesElement = string | Promise<string>;
@@ -370,22 +371,9 @@ export type EcoChildren = string | Promise<string> | number | bigint | boolean |
  * Represents the input configuration for EcoPages.
  */
 export type EcoPagesConfig = Omit<Partial<EcoPagesAppConfig>, 'baseUrl' | 'derivedPaths' | 'templatesExt' | 'integrationsDependencies'> & Pick<EcoPagesAppConfig, 'baseUrl' | 'rootDir'>;
-/**
- * Internal metadata injected by eco-component-meta-plugin.
- * Contains component file path and integration info for dependency resolution.
- * @internal
- */
-export interface EcoInjectedMeta {
-    /** Hashed identifier for client-side use (doesn't expose file paths) */
-    id: string;
-    /** Full file path of the component (use path.dirname() to get directory) */
-    file: string;
-    /** The integration identifier (e.g., 'react', 'kitajs', 'lit', 'ghtml', 'mdx') */
-    integration: string;
-}
 export type EcoComponentConfig = {
-    /** @internal Injected by eco-component-meta-plugin */
-    __eco?: EcoInjectedMeta;
+    /** Canonical integration, module, and stable component attribution. */
+    identity?: ComponentIdentity;
     /**
      * Explicit integration override for this component.
      * When provided, this takes precedence over auto-detected integration metadata.
@@ -799,6 +787,14 @@ export type RouteRendererOptions = {
     params?: PageParams;
     query?: PageQuery;
     locals?: RequestLocals;
+    /**
+     * Preloaded page module from request-time inspection.
+     *
+     * @remarks
+     * When present, render preparation reuses this module instead of importing the
+     * page file again for the same request.
+     */
+    pageModule?: EcoPageFile;
     /**
      * Extra props merged into the page props for this render.
      * @remarks Used by semantic error pages (for example development `message` /
@@ -817,6 +813,8 @@ export type RouteRenderResult = {
     body: RouteRendererBody;
     /** Cache strategy from page component's eco.page({ cache }) option */
     cacheStrategy?: CacheStrategy;
+    /** Source paths observed during render preparation for HTML cache invalidation. */
+    sourceDependencyPaths?: readonly string[];
 };
 /**
  * Represents the dependencies required for an integration plugin.
@@ -888,6 +886,8 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     pageProps?: Record<string, unknown>;
     cacheStrategy?: CacheStrategy;
     pageLocals?: RequestLocals;
+    /** @internal Source paths from render preparation for HTML cache dependency registration. */
+    sourceDependencyPaths?: readonly string[];
 };
 /**
  * Structured page asset package produced after dependency resolution.

package/src/watchers/project-watcher.js

@@ -4,6 +4,7 @@ import { fileSystem } from '@ecopages/file-system';
 import { appLogger } from '../global/app-logger.js';
 import { DevelopmentInvalidationService, } from '../services/invalidation/development-invalidation.service.js';
 import { prepareHmrFileChange } from '../hmr/hmr-file-change-prep.js';
+import { invalidateAppPageCacheBySourcePaths, clearAppPageCache } from '../services/cache/page-cache-service.js';
 import { getAppPageBrowserGraphSession } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
 import { isRegisteredDevTransformEntrypoint } from '../hmr/hmr-entrypoint-output.js';
 import { resolveInternalExecutionDir } from '../utils/resolve-work-dir.js';
@@ -163,6 +164,12 @@ export class ProjectWatcher {
             }
             this.uncacheModules();
             const resolvedFilePath = path.resolve(filePath);
+            if (shouldClearAllPageHtmlCache(plan.category)) {
+                await clearAppPageCache(this.appConfig);
+            }
+            else {
+                await invalidateAppPageCacheBySourcePaths(this.appConfig, [resolvedFilePath]);
+            }
             const graphPreparation = this.hmrManager.isEnabled()
                 ? prepareHmrFileChange(this.appConfig, resolvedFilePath)
                 : undefined;
@@ -404,3 +411,10 @@ export class ProjectWatcher {
         await this.changeQueue.catch(() => undefined);
     }
 }
+function shouldClearAllPageHtmlCache(category) {
+    return (category === 'other' ||
+        category === 'server-source' ||
+        category === 'additional-watch' ||
+        category === 'include-source' ||
+        category === 'explicit-server-view');
+}