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

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

@@ -1,6 +1,7 @@
 import { invariant } from '../../utils/invariant.js';
 import { getAppModuleLoader } from '../../services/module-loading/app-server-module-transpiler.service.js';
 import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.js';
+import { HttpError } from '../../errors/http-error.js';
 /**
  * Loads route page modules and normalizes their data hooks for rendering.
  *
@@ -39,7 +40,6 @@ export class PageModuleLoaderService {
                 rootDir: this.appConfig.rootDir,
                 outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
                 bypassCache: options?.bypassCache,
-                cacheScope: options?.cacheScope,
                 transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
                 noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`,
             });
@@ -65,7 +65,11 @@ export class PageModuleLoaderService {
             })
                 .then((data) => data)
                 .catch((err) => {
-                throw new Error(`Error fetching static props: ${err.message}`);
+                if (HttpError.isHttpError(err) || err instanceof Response) {
+                    throw err;
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`Error fetching static props: ${message}`, { cause: err });
             })
             : {
                 props: {},
@@ -98,9 +102,11 @@ export class PageModuleLoaderService {
      * When both component static methods and module exports exist, component statics win.
      */
     async resolvePageModule(options) {
-        const module = await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file);
+        const module = options.pageModule ??
+            (await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file));
         const { default: Page, getStaticProps: moduleGetStaticProps, getMetadata: moduleGetMetadata, ...integrationSpecificProps } = module;
         return {
+            module,
             Page,
             getStaticProps: Page.staticProps ?? moduleGetStaticProps,
             getMetadata: Page.metadata ?? moduleGetMetadata,

package/src/route-renderer/page-loading/resolved-page-dependencies.d.ts

@@ -0,0 +1,12 @@
+import type { EcoComponent, PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../../types/public-types.js';
+import { collectFileScopedDependencyComponents } from './file-scoped-dependency-components.js';
+export type ResolvedPageDependencies = {
+    ownerFile: string;
+    components: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
+    contribution?: PageBrowserGraphContribution;
+};
+export type ResolvePageDependenciesContribution = (dependencies: Parameters<typeof collectFileScopedDependencyComponents>[0]['dependencies'], ownerFile: string, components: ReadonlyArray<EcoComponent | Partial<EcoComponent>>) => Promise<PageBrowserGraphContribution | undefined>;
+/**
+ * Resolves `eco.page().dependencies()` once for one graph contribution context.
+ */
+export declare function resolvePageDependenciesFromContext(context: PageBrowserGraphContributionContext, integrationName: string, materializeContribution: ResolvePageDependenciesContribution): Promise<ResolvedPageDependencies | undefined>;

package/src/route-renderer/page-loading/resolved-page-dependencies.js

@@ -0,0 +1,38 @@
+import { collectFileScopedDependencyComponents, splitPageDependenciesResult, } from './file-scoped-dependency-components.js';
+/**
+ * Resolves `eco.page().dependencies()` once for one graph contribution context.
+ */
+export async function resolvePageDependenciesFromContext(context, integrationName, materializeContribution) {
+    const pageComponent = context.pageModule.default;
+    const resolveDependencies = pageComponent.resolveDependencies;
+    if (!resolveDependencies) {
+        return undefined;
+    }
+    const dependenciesResult = await resolveDependencies({
+        props: (context.props ?? {}),
+        params: context.params,
+        query: context.query,
+    });
+    if (!dependenciesResult) {
+        return undefined;
+    }
+    const { dependencies, ownerFile } = splitPageDependenciesResult(dependenciesResult);
+    const resolvedOwnerFile = ownerFile ?? context.file;
+    const components = collectFileScopedDependencyComponents({
+        ownerFile: resolvedOwnerFile,
+        integrationName,
+        dependencies,
+    });
+    if (components.length === 0) {
+        return {
+            ownerFile: resolvedOwnerFile,
+            components,
+        };
+    }
+    const contribution = await materializeContribution(dependencies, resolvedOwnerFile, components);
+    return {
+        ownerFile: resolvedOwnerFile,
+        components,
+        contribution,
+    };
+}

package/src/router/README.md

@@ -60,6 +60,14 @@ Match priority:
 
 ## `client/`
 
+### View transitions (`@ecopages/core/client/view-transitions`)
+
+Shared helpers used by `@ecopages/browser-router` and `@ecopages/react-router`:
+
+- `applyViewTransitionNames` / `clearViewTransitionNames` — named `data-view-transition` morph / fade styles (`eco-vt-dynamic-styles`).
+- `ensureRootViewTransitionStyles` — persisted CSS (`eco-vt-root-styles`, `data-eco-persist`) with `html { view-transition-name: none }` when VT is enabled.
+- `documentHasNamedViewTransitions` / `navigationHasNamedViewTransitions` — gate `startViewTransition` to pages with `data-view-transition` markup.
+
 ### Navigation Coordinator (`navigation-coordinator.ts`)
 
 A singleton browser-side runtime stored on `window.__ECO_PAGES__.navigation`.

package/src/services/README.md

@@ -18,11 +18,16 @@ Typical responsibilities include:
 
 - `module-loading/`: framework-owned config/app bootstrap loading and server-side source loading
 - `assets/`: shared browser build coordination and processed asset pipelines
+- `cache/`: page HTML cache stores, selective source-path invalidation, and request coordination
 - `invalidation/`: file-change classification and invalidation policy
 - `runtime-state/`: app-owned invalidation state and dependency graphs
 - `runtime-manifest/`: node runtime manifest derivation and persistence
 - `html/`: final HTML dependency injection and rewriter selection
 
+The asset-processing service caches emitted file assets by source identity in development as well as production.
+When a source file changes, its source hash or explicit invalidation removes the cached asset before the next render,
+so shared layout styles do not need to be rebuilt for every navigated page while HMR remains fresh.
+
 ## Design Rule
 
 If a concern affects more than one integration or more than one runtime adapter, it usually belongs here instead of in a package-specific implementation.

package/src/services/assets/asset-processing-service/asset-processing.service.d.ts

@@ -89,6 +89,7 @@ export declare class AssetProcessingService {
      * Stores one processed asset in the dependency cache.
      */
     private setCachedAsset;
+    private getFileSourceHash;
     /**
      * Clears all cached processed assets.
      */

package/src/services/assets/asset-processing-service/asset-processing.service.js

@@ -229,16 +229,22 @@ export class AssetProcessingService {
      * Returns the cached processed asset for a dependency key when available.
      */
     getCachedAsset(dep, depKey) {
-        if (process.env.NODE_ENV !== 'production' && dep.source === 'file' && dep.kind === 'stylesheet') {
-            return null;
-        }
         if (dep.kind === 'script' && dep.source === 'content') {
             return this.getCachedContentScriptAsset(dep, depKey);
         }
+        const sourceHash = this.getFileSourceHash(dep);
+        if (dep.source === 'file' && sourceHash === undefined) {
+            this.cache.delete(depKey);
+            return null;
+        }
         const cached = this.cache.get(depKey);
         if (!cached) {
             return null;
         }
+        if (cached.sourceHash !== sourceHash) {
+            this.cache.delete(depKey);
+            return null;
+        }
         if (cached.asset.filepath && !fileSystem.exists(cached.asset.filepath)) {
             this.cache.delete(depKey);
             return null;
@@ -269,7 +275,16 @@ export class AssetProcessingService {
      * Stores one processed asset in the dependency cache.
      */
     setCachedAsset(dep, depKey, asset) {
-        this.cache.set(depKey, { asset });
+        this.cache.set(depKey, {
+            asset,
+            sourceHash: this.getFileSourceHash(dep),
+        });
+    }
+    getFileSourceHash(dep) {
+        if (dep.source !== 'file' || !('filepath' in dep) || !fileSystem.exists(dep.filepath)) {
+            return undefined;
+        }
+        return fileSystem.hash(dep.filepath);
     }
     /**
      * Clears all cached processed assets.
@@ -282,7 +297,9 @@ export class AssetProcessingService {
      */
     invalidateCacheForFile(filepath) {
         for (const [key, value] of this.cache.entries()) {
-            if (value.asset.filepath === filepath) {
+            if (value.asset.filepath === filepath ||
+                value.asset.sourceFilepath === filepath ||
+                value.asset.bundledSourceFilepaths?.includes(filepath)) {
                 this.cache.delete(key);
             }
         }

package/src/services/cache/cache.types.d.ts

@@ -8,6 +8,8 @@
 export interface RenderResult {
     html: string;
     strategy: CacheStrategy;
+    /** Source paths that contributed to this render; used for selective HTML cache invalidation. */
+    sourceDependencyPaths?: readonly string[];
 }
 /**
  * Render strategy configuration for pages.
@@ -83,8 +85,8 @@ export interface CacheConfig {
     defaultStrategy?: CacheStrategy;
     /**
      * Whether caching is enabled.
-     * Automatically disabled in dev mode unless explicitly set.
-     * @default true (production), false (development)
+     * In watch mode, defaults to `false` unless explicitly enabled.
+     * @default true in production builds, false in watch when omitted
      */
     enabled?: boolean;
     /**

package/src/services/cache/html-page-cache-dependency-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Maps source dependency paths to rendered HTML cache keys for selective invalidation.
+ */
+export declare class HtmlPageCacheDependencyIndex {
+    private readonly sourcePathToCacheKeys;
+    private readonly cacheKeyToSourcePaths;
+    /**
+     * Records which source paths contributed to one cached HTML entry.
+     */
+    register(cacheKey: string, sourcePaths: readonly string[]): void;
+    /**
+     * Removes dependency metadata for one cache key.
+     */
+    unregister(cacheKey: string): void;
+    /**
+     * Returns cache keys that depend on any of the given source paths.
+     */
+    resolveCacheKeysForSourcePaths(sourcePaths: readonly string[]): string[];
+    clear(): void;
+}
+type CollectHtmlCacheSourceDependencyPathsInput = {
+    routeFile: string;
+    processedAssets: readonly {
+        sourceFilepath?: string;
+        bundledSourceFilepaths?: readonly string[];
+    }[];
+    graphDependencyPaths?: ReadonlySet<string>;
+    additionalSourcePaths?: readonly string[];
+};
+/**
+ * Merges route, graph, processed-asset, and caller-supplied source paths for HTML cache invalidation.
+ */
+export declare function collectHtmlCacheSourceDependencyPaths(input: CollectHtmlCacheSourceDependencyPathsInput): string[];
+export {};

package/src/services/cache/html-page-cache-dependency-index.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+/**
+ * Maps source dependency paths to rendered HTML cache keys for selective invalidation.
+ */
+export class HtmlPageCacheDependencyIndex {
+    sourcePathToCacheKeys = new Map();
+    cacheKeyToSourcePaths = new Map();
+    /**
+     * Records which source paths contributed to one cached HTML entry.
+     */
+    register(cacheKey, sourcePaths) {
+        this.unregister(cacheKey);
+        if (sourcePaths.length === 0) {
+            return;
+        }
+        const normalizedSourcePaths = new Set(sourcePaths.map((sourcePath) => normalizeSourcePath(sourcePath)));
+        this.cacheKeyToSourcePaths.set(cacheKey, normalizedSourcePaths);
+        for (const sourcePath of normalizedSourcePaths) {
+            const cacheKeys = this.sourcePathToCacheKeys.get(sourcePath) ?? new Set();
+            cacheKeys.add(cacheKey);
+            this.sourcePathToCacheKeys.set(sourcePath, cacheKeys);
+        }
+    }
+    /**
+     * Removes dependency metadata for one cache key.
+     */
+    unregister(cacheKey) {
+        const sourcePaths = this.cacheKeyToSourcePaths.get(cacheKey);
+        if (!sourcePaths) {
+            return;
+        }
+        for (const sourcePath of sourcePaths) {
+            const cacheKeys = this.sourcePathToCacheKeys.get(sourcePath);
+            cacheKeys?.delete(cacheKey);
+            if (cacheKeys?.size === 0) {
+                this.sourcePathToCacheKeys.delete(sourcePath);
+            }
+        }
+        this.cacheKeyToSourcePaths.delete(cacheKey);
+    }
+    /**
+     * Returns cache keys that depend on any of the given source paths.
+     */
+    resolveCacheKeysForSourcePaths(sourcePaths) {
+        const cacheKeys = new Set();
+        for (const sourcePath of sourcePaths) {
+            const normalizedSourcePath = normalizeSourcePath(sourcePath);
+            const matches = this.sourcePathToCacheKeys.get(normalizedSourcePath);
+            if (!matches) {
+                continue;
+            }
+            for (const cacheKey of matches) {
+                cacheKeys.add(cacheKey);
+            }
+        }
+        return [...cacheKeys];
+    }
+    clear() {
+        this.sourcePathToCacheKeys.clear();
+        this.cacheKeyToSourcePaths.clear();
+    }
+}
+function normalizeSourcePath(sourcePath) {
+    return path.resolve(sourcePath);
+}
+/**
+ * Merges route, graph, processed-asset, and caller-supplied source paths for HTML cache invalidation.
+ */
+export function collectHtmlCacheSourceDependencyPaths(input) {
+    const sourcePaths = new Set([normalizeSourcePath(input.routeFile)]);
+    for (const additionalPath of input.additionalSourcePaths ?? []) {
+        sourcePaths.add(normalizeSourcePath(additionalPath));
+    }
+    if (input.graphDependencyPaths) {
+        for (const graphPath of input.graphDependencyPaths) {
+            sourcePaths.add(normalizeSourcePath(graphPath));
+        }
+    }
+    for (const asset of input.processedAssets) {
+        if (asset.sourceFilepath) {
+            sourcePaths.add(normalizeSourcePath(asset.sourceFilepath));
+        }
+        for (const bundledSourceFilepath of asset.bundledSourceFilepaths ?? []) {
+            sourcePaths.add(normalizeSourcePath(bundledSourceFilepath));
+        }
+    }
+    return [...sourcePaths];
+}

package/src/services/cache/index.d.ts

@@ -4,4 +4,6 @@
  */
 export type { CacheConfig, CacheEntry, CacheResult, CacheStats, CacheStore, CacheStrategy, RenderResult, } from './cache.types.js';
 export { MemoryCacheStore, type MemoryCacheStoreOptions } from './memory-cache-store.js';
+export { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
 export { getCacheControlHeader, PageCacheService, type PageCacheServiceOptions } from './page-cache-service.js';
+export { clearAppPageCache, getAppPageCacheService, invalidateAppPageCacheBySourcePaths, registerAppPageCacheService, } from './page-cache-service.js';

package/src/services/cache/index.js

@@ -3,4 +3,6 @@
  * @module
  */
 export { MemoryCacheStore } from './memory-cache-store.js';
+export { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
 export { getCacheControlHeader, PageCacheService } from './page-cache-service.js';
+export { clearAppPageCache, getAppPageCacheService, invalidateAppPageCacheBySourcePaths, registerAppPageCacheService, } from './page-cache-service.js';

package/src/services/cache/page-cache-service.d.ts

@@ -3,10 +3,13 @@
  * Handles stale-while-revalidate semantics and background regeneration.
  * @module
  */
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { CacheResult, CacheStore, CacheStrategy, RenderResult } from './cache.types.js';
+import { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
 export interface PageCacheServiceOptions {
     store?: CacheStore;
     enabled?: boolean;
+    dependencyIndex?: HtmlPageCacheDependencyIndex;
 }
 /**
  * Core page caching service with ISR support.
@@ -14,7 +17,9 @@ export interface PageCacheServiceOptions {
 export declare class PageCacheService {
     private store;
     private enabled;
+    private readonly dependencyIndex;
     private regenerationPromises;
+    private missPromises;
     constructor(options?: PageCacheServiceOptions);
     /**
      * Generate a cache key from URL and optional params.
@@ -35,7 +40,11 @@ export declare class PageCacheService {
      * @param defaultStrategy - Default strategy if page doesn't specify one
      * @param renderFn - Function that renders the page and returns HTML + strategy
      */
-    getOrCreate(key: string, defaultStrategy: CacheStrategy, renderFn: () => Promise<RenderResult>): Promise<CacheResult>;
+    getOrCreate(key: string, defaultStrategy: CacheStrategy, renderFn: () => Promise<RenderResult>, options?: {
+        sourceDependencyPaths?: readonly string[];
+    }): Promise<CacheResult>;
+    private resolveOrCreate;
+    private registerDependencyPaths;
     /**
      * Regenerate content in the background without blocking the response.
      * Uses promise deduplication to prevent multiple concurrent regenerations.
@@ -49,6 +58,11 @@ export declare class PageCacheService {
      * Invalidate cache entries by paths.
      */
     invalidateByPaths(paths: string[]): Promise<number>;
+    /**
+     * Invalidates cached HTML entries that registered the given source paths.
+     */
+    invalidateBySourceDependencyPaths(sourcePaths: readonly string[]): Promise<number>;
+    getDependencyIndex(): HtmlPageCacheDependencyIndex;
     /**
      * Clear all cached entries.
      */
@@ -68,3 +82,19 @@ export declare class PageCacheService {
  * Generate Cache-Control header value from cache strategy.
  */
 export declare function getCacheControlHeader(strategy: CacheStrategy | 'disabled'): string;
+/**
+ * Registers the page cache service for one app config instance.
+ */
+export declare function registerAppPageCacheService(appConfig: EcoPagesAppConfig, service: PageCacheService | null): void;
+/**
+ * Returns the registered page cache service for one app config, if any.
+ */
+export declare function getAppPageCacheService(appConfig: EcoPagesAppConfig): PageCacheService | null;
+/**
+ * Clears rendered HTML cache entries for one app during development invalidation.
+ */
+export declare function clearAppPageCache(appConfig: EcoPagesAppConfig): Promise<void>;
+/**
+ * Invalidates rendered HTML cache entries that depend on the given source paths.
+ */
+export declare function invalidateAppPageCacheBySourcePaths(appConfig: EcoPagesAppConfig, sourcePaths: readonly string[]): Promise<number>;

package/src/services/cache/page-cache-service.js

@@ -5,16 +5,20 @@
  */
 import { appLogger } from '../../global/app-logger.js';
 import { MemoryCacheStore } from './memory-cache-store.js';
+import { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
 /**
  * Core page caching service with ISR support.
  */
 export class PageCacheService {
     store;
     enabled;
+    dependencyIndex;
     regenerationPromises = new Map();
+    missPromises = new Map();
     constructor(options = {}) {
         this.store = options.store ?? new MemoryCacheStore();
         this.enabled = options.enabled ?? true;
+        this.dependencyIndex = options.dependencyIndex ?? new HtmlPageCacheDependencyIndex();
     }
     /**
      * Generate a cache key from URL and optional params.
@@ -62,20 +66,32 @@ export class PageCacheService {
      * @param defaultStrategy - Default strategy if page doesn't specify one
      * @param renderFn - Function that renders the page and returns HTML + strategy
      */
-    async getOrCreate(key, defaultStrategy, renderFn) {
+    async getOrCreate(key, defaultStrategy, renderFn, options) {
         if (!this.enabled) {
             const { html, strategy } = await renderFn();
             return { html, status: 'miss', strategy };
         }
+        const pendingMiss = this.missPromises.get(key);
+        if (pendingMiss) {
+            return pendingMiss;
+        }
+        const missPromise = this.resolveOrCreate(key, defaultStrategy, renderFn, options).finally(() => {
+            this.missPromises.delete(key);
+        });
+        this.missPromises.set(key, missPromise);
+        return missPromise;
+    }
+    async resolveOrCreate(key, defaultStrategy, renderFn, options) {
         const entry = await this.store.get(key);
         if (!entry) {
-            const { html, strategy } = await renderFn();
+            const { html, strategy, sourceDependencyPaths } = await renderFn();
             const effectiveStrategy = strategy ?? defaultStrategy;
             if (effectiveStrategy === 'dynamic') {
                 return { html, status: 'miss', strategy: effectiveStrategy };
             }
             const newEntry = this.createEntry(html, effectiveStrategy);
             await this.store.set(key, newEntry);
+            this.registerDependencyPaths(key, options?.sourceDependencyPaths, sourceDependencyPaths);
             return { html, status: 'miss', strategy: effectiveStrategy };
         }
         if (!this.isStale(entry)) {
@@ -84,6 +100,18 @@ export class PageCacheService {
         this.regenerateInBackground(key, entry.strategy, renderFn);
         return { html: entry.html, status: 'stale', strategy: entry.strategy };
     }
+    registerDependencyPaths(key, initialPaths, renderedPaths) {
+        const mergedPaths = new Set();
+        for (const sourcePath of initialPaths ?? []) {
+            mergedPaths.add(sourcePath);
+        }
+        for (const sourcePath of renderedPaths ?? []) {
+            mergedPaths.add(sourcePath);
+        }
+        if (mergedPaths.size > 0) {
+            this.dependencyIndex.register(key, [...mergedPaths]);
+        }
+    }
     /**
      * Regenerate content in the background without blocking the response.
      * Uses promise deduplication to prevent multiple concurrent regenerations.
@@ -94,10 +122,11 @@ export class PageCacheService {
         }
         const regeneratePromise = (async () => {
             try {
-                const { html, strategy } = await renderFn();
+                const { html, strategy, sourceDependencyPaths } = await renderFn();
                 const effectiveStrategy = strategy ?? fallbackStrategy;
                 const newEntry = this.createEntry(html, effectiveStrategy);
                 await this.store.set(key, newEntry);
+                this.registerDependencyPaths(key, undefined, sourceDependencyPaths);
                 return html;
             }
             finally {
@@ -123,10 +152,28 @@ export class PageCacheService {
     async invalidateByPaths(paths) {
         return this.store.invalidateByPaths(paths);
     }
+    /**
+     * Invalidates cached HTML entries that registered the given source paths.
+     */
+    async invalidateBySourceDependencyPaths(sourcePaths) {
+        const cacheKeys = this.dependencyIndex.resolveCacheKeysForSourcePaths(sourcePaths);
+        let count = 0;
+        for (const cacheKey of cacheKeys) {
+            if (await this.store.delete(cacheKey)) {
+                count += 1;
+            }
+            this.dependencyIndex.unregister(cacheKey);
+        }
+        return count;
+    }
+    getDependencyIndex() {
+        return this.dependencyIndex;
+    }
     /**
      * Clear all cached entries.
      */
     async clear() {
+        this.dependencyIndex.clear();
         return this.store.clear();
     }
     /**
@@ -161,3 +208,32 @@ export function getCacheControlHeader(strategy) {
     }
     return 'no-store';
 }
+const pageCacheByAppConfig = new WeakMap();
+/**
+ * Registers the page cache service for one app config instance.
+ */
+export function registerAppPageCacheService(appConfig, service) {
+    if (service) {
+        pageCacheByAppConfig.set(appConfig, service);
+        return;
+    }
+    pageCacheByAppConfig.delete(appConfig);
+}
+/**
+ * Returns the registered page cache service for one app config, if any.
+ */
+export function getAppPageCacheService(appConfig) {
+    return pageCacheByAppConfig.get(appConfig) ?? null;
+}
+/**
+ * Clears rendered HTML cache entries for one app during development invalidation.
+ */
+export async function clearAppPageCache(appConfig) {
+    await getAppPageCacheService(appConfig)?.clear();
+}
+/**
+ * Invalidates rendered HTML cache entries that depend on the given source paths.
+ */
+export async function invalidateAppPageCacheBySourcePaths(appConfig, sourcePaths) {
+    return (await getAppPageCacheService(appConfig)?.invalidateBySourceDependencyPaths(sourcePaths)) ?? 0;
+}

package/src/services/cache/page-request-cache-coordinator.service.js

@@ -1,4 +1,5 @@
 import { getCacheControlHeader } from './page-cache-service.js';
+import { getRequestPipelineMetricsHeaderName, isRequestPipelineMetricsEnabled, serializeRequestPipelineMetricsHeader, } from '../../diagnostics/request-pipeline-metrics.js';
 /**
  * Coordinates request-time page caching concerns around one render invocation.
  *
@@ -104,6 +105,9 @@ export class PageRequestCacheCoordinator {
             'Cache-Control': getCacheControlHeader(cacheStatus === 'disabled' ? 'disabled' : strategy),
             'X-Cache': cacheStatus.toUpperCase(),
         };
+        if (isRequestPipelineMetricsEnabled()) {
+            headers[getRequestPipelineMetricsHeaderName()] = serializeRequestPipelineMetricsHeader();
+        }
         return new Response(html, { headers });
     }
 }

package/src/services/module-loading/README.md

@@ -12,11 +12,11 @@ Call site (route scan, renderer, SSG, API)
        └─ PageModuleImportService.importModule()
             ├─ dev + host loader → host runtime (Node only, when configured)
             ├─ production disk cache → route-module build cache
-            ├─ unified pages graph → prebuilt chunk import
+            ├─ unified pages graph → prebuilt chunk import (production only)
             └─ Rolldown per-page build → dynamic import of transpiled output
 ```
 
-`ServerModuleTranspiler` is a thin wrapper that injects `rootDir`, optional default plugins, and invalidation version into the same `PageModuleImportService` path. App code should prefer `getAppModuleLoader(appConfig)` or `getAppServerModuleTranspiler(appConfig)`.
+`ServerModuleTranspiler` is a thin wrapper that injects `rootDir` and optional default plugins into the same `PageModuleImportService` path. App code should prefer `getAppModuleLoader(appConfig)` or `getAppServerModuleTranspiler(appConfig)`.
 
 ## Host vs app ownership
 
@@ -29,15 +29,18 @@ Call site (route scan, renderer, SSG, API)
 
 ## Caching layers
 
-1. **In-memory promise cache** (`PageModuleImportService.importCache`) — keyed by file path, resolved `outdir`, JSX/plugin inputs, file hash, and invalidation version. Cleared by `invalidateDevelopmentGraph()`.
-2. **Disk transpile cache** (`.eco/.server-modules/.build-cache.json`) — production only; see route-module build cache slice.
-3. **Unified graph manifest** — production static export fast path; see build layer docs.
+1. **In-memory promise cache** (`PageModuleImportService.importCache`) — keyed by runtime, file path, content-derived reuse identity (`createRouteModuleReuseIdentity`), and source hash. Cleared by `invalidateDevelopmentGraph()`.
+2. **Disk transpile cache** (`.eco/.server-modules/.build-cache.json`) — production and stable development graphs when dependency hashes match. Manifest field `corePackageVersion` invalidates entries when the framework package changes.
+3. **Unified graph manifest** — production static export fast path only; see build layer docs.
+
+Development `?update=` query params use `sourceHash` plus a per-service import generation counter so Node and Bun bust ESM module cache after `invalidateDevelopmentGraph()` without a process-wide invalidation version in reuse keys.
 
 ## Files
 
 | File                                      | Role                                                      |
 | ----------------------------------------- | --------------------------------------------------------- |
 | `page-module-import.service.ts`           | Core import/cache/build orchestration                     |
+| `route-module-build-manifest.ts`          | Content-derived reuse identity and disk cache manifest    |
 | `app-module-loader.service.ts`            | App-facing loader interface                               |
 | `app-server-module-transpiler.service.ts` | Factory for app-scoped loader + transpiler                |
 | `server-module-transpiler.service.ts`     | Injectable transpiler boundary for tests and bootstrap    |
@@ -46,4 +49,4 @@ Call site (route scan, renderer, SSG, API)
 
 ## Development invalidation
 
-`DevelopmentInvalidationService.invalidateServerModules()` bumps the app-owned invalidation version and calls `appModuleLoader.invalidateDevelopmentGraph()`, which clears the in-memory import cache and increments the per-service invalidation counter used in cache keys and dev `?update=` query params.
+`DevelopmentInvalidationService.invalidateServerModules()` calls `appModuleLoader.invalidateDevelopmentGraph()`, which clears the in-memory import cache, bumps the per-service dev import generation used only for `?update=` URLs, and clears dependency-hash memoization. Route-module disk reuse stays content-derived: unchanged source and dependency hashes keep their entries until the edited module or its graph changes.

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

@@ -43,7 +43,6 @@ export function setAppHostModuleLoader(appConfig, hostModuleLoader) {
  * {@link createServerBuildRequest}; this loader does not merge app plugins.
  */
 export function createAppModuleLoader(appConfig) {
-    const invalidationService = new DevelopmentInvalidationService(appConfig);
     const pageModuleImportService = new PageModuleImportService(appConfig, {
         canLoadSourceModuleFromHost: (filePath) => shouldAppUseHostModuleLoader(appConfig, filePath),
         getHostModuleLoader: () => getAppHostModuleLoader(appConfig),
@@ -54,11 +53,9 @@ export function createAppModuleLoader(appConfig) {
         },
         pageModuleImportService,
         async importModule(options) {
-            const invalidationVersion = options.invalidationVersion ?? invalidationService.getServerModuleInvalidationVersion();
             return await pageModuleImportService.importModule({
                 ...options,
                 buildExecutor: options.buildExecutor ?? requireBuildRuntime(appConfig).getProfile('route-module'),
-                invalidationVersion,
             });
         },
         invalidateDevelopmentGraph() {