@ecopages/core 0.2.0-beta.41 → 0.2.0-beta.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.41",
+  "version": "0.2.0-beta.43",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.41",
+    "@ecopages/file-system": "0.2.0-beta.43",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.141.0",
@@ -32,7 +32,7 @@
     "@standard-schema/utils": "^0.3.0"
   },
   "peerDependencies": {
-    "@ecopages/dev-toolbar": "0.2.0-beta.41"
+    "@ecopages/dev-toolbar": "0.2.0-beta.43"
   },
   "peerDependenciesMeta": {
     "@ecopages/dev-toolbar": {
@@ -283,6 +283,10 @@
       "types": "./src/plugins/tsconfig-import-resolver.d.ts",
       "default": "./src/plugins/tsconfig-import-resolver.js"
     },
+    "./plugins/package-specifier": {
+      "types": "./src/plugins/package-specifier.d.ts",
+      "default": "./src/plugins/package-specifier.js"
+    },
     "./plugins/jsx-import-source.utils": {
       "types": "./src/plugins/jsx-import-source.utils.d.ts",
       "default": "./src/plugins/jsx-import-source.utils.js"
@@ -576,6 +580,10 @@
       "types": "./src/plugins/tsconfig-import-resolver.d.ts",
       "default": "./src/plugins/tsconfig-import-resolver.js"
     },
+    "./plugins/package-specifier.ts": {
+      "types": "./src/plugins/package-specifier.d.ts",
+      "default": "./src/plugins/package-specifier.js"
+    },
     "./plugins/jsx-import-source.utils.ts": {
       "types": "./src/plugins/jsx-import-source.utils.d.ts",
       "default": "./src/plugins/jsx-import-source.utils.js"

package/src/adapters/shared/http/fs-server-response-matcher.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { appLogger } from '../../../global/app-logger.js';
 import { PageRequestCacheCoordinator } from '../../../services/cache/page-request-cache-coordinator.service.js';
+import { getBrowserRuntimeAssetGeneration } from '../../../services/assets/browser-runtime-asset-generation.js';
 import { ServerUtils } from '../../../utils/server-utils.module.js';
 import { FileRouteMiddlewarePipeline } from './file-route-middleware-pipeline.js';
 import { HttpError } from '../../../errors/http-error.js';
@@ -27,7 +28,7 @@ export class FileSystemResponseMatcher {
         this.router = router;
         this.routeRendererFactory = routeRendererFactory;
         this.fileSystemResponseFactory = fileSystemResponseFactory;
-        this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy);
+        this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy, () => getBrowserRuntimeAssetGeneration(this.appConfig));
         this.fileRouteMiddlewarePipeline = new FileRouteMiddlewarePipeline(cacheService);
     }
     /**
@@ -169,6 +170,7 @@ export class FileSystemResponseMatcher {
         const result = await routeRenderer.execute({
             file: templatePath,
             props,
+            locals: {},
         });
         return createHtmlResponse(result.body);
     }

package/src/build/browser/browser-runtime-manifest.d.ts

@@ -29,3 +29,7 @@ export declare class BrowserRuntimeManifestConflictError extends Error {
 export declare function createBrowserRuntimeManifest(declarations?: readonly BrowserRuntimeAssetDeclaration[]): BrowserRuntimeManifest;
 export declare function mergeBrowserRuntimeManifests(...manifests: Array<BrowserRuntimeManifest | undefined>): BrowserRuntimeManifest;
 export declare function getBrowserRuntimeSpecifierMap(manifest: BrowserRuntimeManifest): ReadonlyMap<string, string>;
+/** Resolves a runtime public URL for an exact specifier. */
+export declare function resolveRuntimeSpecifierPublicPath(specifier: string, publicPathsBySpecifier: ReadonlyMap<string, string>): string | undefined;
+/** Resolves a manifest-owned runtime public URL for an exact specifier. */
+export declare function resolveBrowserRuntimePublicPath(specifier: string, manifest: BrowserRuntimeManifest): string | undefined;

package/src/build/browser/browser-runtime-manifest.js

@@ -18,8 +18,7 @@ function normalizeDeclaration(declaration) {
     };
 }
 function hasCompatibleRuntimeAsset(existing, incoming) {
-    return (existing.owner === incoming.owner &&
-        existing.importPath === incoming.importPath &&
+    return (existing.importPath === incoming.importPath &&
         existing.publicPath === incoming.publicPath &&
         existing.mode === incoming.mode &&
         arrayEquals(existing.externals, incoming.externals));
@@ -56,3 +55,11 @@ export function mergeBrowserRuntimeManifests(...manifests) {
 export function getBrowserRuntimeSpecifierMap(manifest) {
     return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
 }
+/** Resolves a runtime public URL for an exact specifier. */
+export function resolveRuntimeSpecifierPublicPath(specifier, publicPathsBySpecifier) {
+    return publicPathsBySpecifier.get(specifier);
+}
+/** Resolves a manifest-owned runtime public URL for an exact specifier. */
+export function resolveBrowserRuntimePublicPath(specifier, manifest) {
+    return manifest.bySpecifier.get(specifier)?.publicPath;
+}

package/src/build/browser/browser-runtime-plugin-helpers.d.ts

@@ -5,7 +5,7 @@
  * `createBrowserRuntimePlugin` needs to:
  *
  * 1. Escape each specifier for inclusion in a regex filter.
- * 2. Build a `RegExp` whose alternation matches any of those specifiers.
+ * 2. Build a `RegExp` whose alternation matches registered specifiers.
  *
  * These utilities are extracted here so the plugin does not duplicate
  * the same code path.
@@ -17,10 +17,8 @@
  */
 export declare function escapeRegExp(value: string): string;
 /**
- * Builds a `RegExp` whose alternation matches any of the keys in
- * `specifierMap`.
+ * Builds a `RegExp` that matches registered specifiers exactly.
  *
- * Returns `null` for an empty map so callers can short-circuit and
- * avoid registering a no-op `onResolve` / `onLoad` filter.
+ * Returns `null` for an empty map so callers can short-circuit registration.
  */
 export declare function buildSpecifierFilter(specifierMap: ReadonlyMap<string, string>): RegExp | null;

package/src/build/browser/browser-runtime-plugin-helpers.js

@@ -5,7 +5,7 @@
  * `createBrowserRuntimePlugin` needs to:
  *
  * 1. Escape each specifier for inclusion in a regex filter.
- * 2. Build a `RegExp` whose alternation matches any of those specifiers.
+ * 2. Build a `RegExp` whose alternation matches registered specifiers.
  *
  * These utilities are extracted here so the plugin does not duplicate
  * the same code path.
@@ -19,16 +19,14 @@ export function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 /**
- * Builds a `RegExp` whose alternation matches any of the keys in
- * `specifierMap`.
+ * Builds a `RegExp` that matches registered specifiers exactly.
  *
- * Returns `null` for an empty map so callers can short-circuit and
- * avoid registering a no-op `onResolve` / `onLoad` filter.
+ * Returns `null` for an empty map so callers can short-circuit registration.
  */
 export function buildSpecifierFilter(specifierMap) {
     if (specifierMap.size === 0) {
         return null;
     }
     const alternation = Array.from(specifierMap.keys()).map(escapeRegExp).join('|');
-    return new RegExp(`^(${alternation})$`);
+    return new RegExp(`^(?:${alternation})$`);
 }

package/src/build/browser/browser-runtime-plugin.d.ts

@@ -11,22 +11,16 @@
  * - `onLoad` for JS/TS files → AST-walking import/export rewrite against the
  *   manifest specifier set, with a `code.includes(specifier)` fast path
  *
- * The plugin object carries the manifest's `specifier → publicPath` map
- * under `BROWSER_RUNTIME_IMPORT_REWRITE_MAP` so
- * `collectBrowserRuntimeImportRewriteMap` and the post-build rewriter can
- * read it without re-walking the manifest.
- *
- * This is the single source of truth for browser-runtime plugin behavior.
- * Per-bundler bridges can treat it as a single plugin.
+ * The plugin object carries the manifest under `BROWSER_RUNTIME_MANIFEST` so
+ * post-build rewriters can resolve exact and subpath imports without rebuilding
+ * the map by hand.
  */
 import type { EcoBuildPlugin } from '../contracts/build-types.js';
 import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
 /**
- * Symbol used to attach the manifest's `specifier → publicPath` map to a
- * plugin instance. Consumers read it via `getBrowserRuntimeImportRewriteMap`
- * or `collectBrowserRuntimeImportRewriteMap`.
+ * Symbol used to attach the browser-runtime manifest to a plugin instance.
  */
-export declare const BROWSER_RUNTIME_IMPORT_REWRITE_MAP: unique symbol;
+export declare const BROWSER_RUNTIME_MANIFEST: unique symbol;
 /**
  * Default name used by `createBrowserRuntimePlugin` when the caller
  * does not provide one.
@@ -63,8 +57,13 @@ export type CreateBrowserRuntimePluginOptions = {
  *
  * Exposed for the post-build rewriter and for tests.
  */
-export declare function rewriteBrowserRuntimeImports(code: string, specifierMap: ReadonlyMap<string, string>, filePath?: string): string;
+export declare function rewriteBrowserRuntimeImports(code: string, manifest: BrowserRuntimeManifest, filePath?: string): string;
+export declare function getBrowserRuntimeManifestFromPlugin(plugin: EcoBuildPlugin): BrowserRuntimeManifest | undefined;
+/**
+ * Returns the exact specifier → publicPath map derived from the plugin manifest.
+ */
 export declare function getBrowserRuntimeImportRewriteMap(plugin: EcoBuildPlugin): ReadonlyMap<string, string> | undefined;
+export declare function collectBrowserRuntimeManifests(plugins: EcoBuildPlugin[] | undefined): BrowserRuntimeManifest[];
 export declare function collectBrowserRuntimeImportRewriteMap(plugins: EcoBuildPlugin[] | undefined): ReadonlyMap<string, string>;
 /**
  * Creates a build plugin that exposes the union of browser-runtime

package/src/build/browser/browser-runtime-plugin.js

@@ -11,25 +11,19 @@
  * - `onLoad` for JS/TS files → AST-walking import/export rewrite against the
  *   manifest specifier set, with a `code.includes(specifier)` fast path
  *
- * The plugin object carries the manifest's `specifier → publicPath` map
- * under `BROWSER_RUNTIME_IMPORT_REWRITE_MAP` so
- * `collectBrowserRuntimeImportRewriteMap` and the post-build rewriter can
- * read it without re-walking the manifest.
- *
- * This is the single source of truth for browser-runtime plugin behavior.
- * Per-bundler bridges can treat it as a single plugin.
+ * The plugin object carries the manifest under `BROWSER_RUNTIME_MANIFEST` so
+ * post-build rewriters can resolve exact and subpath imports without rebuilding
+ * the map by hand.
  */
 import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { parseModuleSource } from '../../cache/module-parse-cache.js';
-import { getBrowserRuntimeSpecifierMap } from './browser-runtime-manifest.js';
+import { getBrowserRuntimeSpecifierMap, mergeBrowserRuntimeManifests, resolveBrowserRuntimePublicPath, } from './browser-runtime-manifest.js';
 import { buildSpecifierFilter } from './browser-runtime-plugin-helpers.js';
 /**
- * Symbol used to attach the manifest's `specifier → publicPath` map to a
- * plugin instance. Consumers read it via `getBrowserRuntimeImportRewriteMap`
- * or `collectBrowserRuntimeImportRewriteMap`.
+ * Symbol used to attach the browser-runtime manifest to a plugin instance.
  */
-export const BROWSER_RUNTIME_IMPORT_REWRITE_MAP = Symbol.for('ecopages.browserRuntimeImportRewriteMap');
+export const BROWSER_RUNTIME_MANIFEST = Symbol.for('ecopages.browserRuntimeManifest');
 /**
  * Default name used by `createBrowserRuntimePlugin` when the caller
  * does not provide one.
@@ -57,7 +51,7 @@ function queueReplacement(options) {
     if (!isRecord(options.source) || typeof options.source.value !== 'string') {
         return;
     }
-    const mappedPath = options.specifierMap.get(options.source.value);
+    const mappedPath = resolveBrowserRuntimePublicPath(options.source.value, options.manifest);
     if (!mappedPath || typeof options.source.start !== 'number' || typeof options.source.end !== 'number') {
         return;
     }
@@ -74,8 +68,8 @@ function queueReplacement(options) {
  *
  * Exposed for the post-build rewriter and for tests.
  */
-export function rewriteBrowserRuntimeImports(code, specifierMap, filePath = 'browser-runtime-imports.js') {
-    if (specifierMap.size === 0) {
+export function rewriteBrowserRuntimeImports(code, manifest, filePath = 'browser-runtime-imports.js') {
+    if (manifest.assets.length === 0) {
         return code;
     }
     const edits = [];
@@ -88,11 +82,11 @@ export function rewriteBrowserRuntimeImports(code, specifierMap, filePath = 'bro
             if (node.type === 'ImportDeclaration' ||
                 node.type === 'ExportNamedDeclaration' ||
                 node.type === 'ExportAllDeclaration') {
-                queueReplacement({ code, source: node.source, specifierMap, edits });
+                queueReplacement({ code, source: node.source, manifest, edits });
             }
             if (node.type === 'ImportExpression' && isRecord(node.source)) {
                 if (node.source.type === 'StringLiteral' || node.source.type === 'Literal') {
-                    queueReplacement({ code, source: node.source, specifierMap, edits });
+                    queueReplacement({ code, source: node.source, manifest, edits });
                 }
             }
             for (const value of Object.values(node)) {
@@ -121,23 +115,31 @@ export function rewriteBrowserRuntimeImports(code, specifierMap, filePath = 'bro
     }
     return rewritten;
 }
+function importMightReferenceRuntimeRoots(code, rootSpecifiers) {
+    return rootSpecifiers.some((specifier) => code.includes(specifier));
+}
+export function getBrowserRuntimeManifestFromPlugin(plugin) {
+    return plugin[BROWSER_RUNTIME_MANIFEST];
+}
+/**
+ * Returns the exact specifier → publicPath map derived from the plugin manifest.
+ */
 export function getBrowserRuntimeImportRewriteMap(plugin) {
-    return plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP];
+    const manifest = getBrowserRuntimeManifestFromPlugin(plugin);
+    return manifest ? getBrowserRuntimeSpecifierMap(manifest) : undefined;
 }
-export function collectBrowserRuntimeImportRewriteMap(plugins) {
-    const merged = new Map();
+export function collectBrowserRuntimeManifests(plugins) {
+    const manifests = [];
     for (const plugin of plugins ?? []) {
-        const specifierMap = getBrowserRuntimeImportRewriteMap(plugin);
-        if (!specifierMap) {
-            continue;
-        }
-        for (const [specifier, publicPath] of specifierMap.entries()) {
-            if (!merged.has(specifier)) {
-                merged.set(specifier, publicPath);
-            }
+        const manifest = getBrowserRuntimeManifestFromPlugin(plugin);
+        if (manifest) {
+            manifests.push(manifest);
         }
     }
-    return merged;
+    return manifests;
+}
+export function collectBrowserRuntimeImportRewriteMap(plugins) {
+    return getBrowserRuntimeSpecifierMap(mergeBrowserRuntimeManifests(...collectBrowserRuntimeManifests(plugins)));
 }
 /**
  * Creates a build plugin that exposes the union of browser-runtime
@@ -159,12 +161,12 @@ export function createBrowserRuntimePlugin(options) {
     const rewriteImports = options.rewriteImports ?? true;
     const matchPublicPaths = options.matchPublicPaths ?? true;
     const publicPathSet = new Set(specifierMap.values());
-    const specifierKeys = Array.from(specifierMap.keys());
+    const rootSpecifiers = manifest.assets.map((asset) => asset.specifier);
     const plugin = {
         name: options.name ?? DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
         setup(build) {
             build.onResolve({ filter: specifierFilter }, (args) => {
-                const mappedPath = specifierMap.get(args.path);
+                const mappedPath = resolveBrowserRuntimePublicPath(args.path, manifest);
                 if (!mappedPath) {
                     return undefined;
                 }
@@ -195,10 +197,10 @@ export function createBrowserRuntimePlugin(options) {
                      * any manifest-owned specifiers. This avoids expensive oxc-parser calls
                      * on every JS/TS file in the dependency graph.
                      */
-                    if (!specifierKeys.some((specifier) => code.includes(specifier))) {
+                    if (!importMightReferenceRuntimeRoots(code, rootSpecifiers)) {
                         return undefined;
                     }
-                    const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, args.path);
+                    const rewritten = rewriteBrowserRuntimeImports(code, manifest, args.path);
                     if (rewritten === code) {
                         return undefined;
                     }
@@ -211,6 +213,6 @@ export function createBrowserRuntimePlugin(options) {
             }
         },
     };
-    plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP] = specifierMap;
+    plugin[BROWSER_RUNTIME_MANIFEST] = manifest;
     return plugin;
 }

package/src/build/rolldown/rolldown-adapter-helpers.js

@@ -12,7 +12,8 @@ import { builtinModules, createRequire } from 'node:module';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { isBarePackageImportSpecifier } from '../../plugins/tsconfig-import-resolver.js';
-import { collectBrowserRuntimeImportRewriteMap, rewriteBrowserRuntimeImports, } from '../browser/browser-runtime-plugin.js';
+import { collectBrowserRuntimeManifests, rewriteBrowserRuntimeImports } from '../browser/browser-runtime-plugin.js';
+import { mergeBrowserRuntimeManifests } from '../browser/browser-runtime-manifest.js';
 import { createServerSideCssShimPlugin } from './server-side-css-shim-plugin.js';
 import { createRolldownPluginBridge } from './rolldown-plugin-bridge.js';
 import { isDeclaredAppPackageImport, isWorkspacePackageImport, normalizeNodeRuntimeBuildOutputs, } from './runtime-build-output-normalizer.js';
@@ -374,13 +375,17 @@ export function rewriteBrowserRuntimeImportsInOutputs(result, contextRoot, plugi
     if (!result.success || result.outputs.length === 0) {
         return result;
     }
-    const specifierMap = collectBrowserRuntimeImportRewriteMap(plugins);
-    if (specifierMap.size === 0) {
+    const manifests = collectBrowserRuntimeManifests(plugins);
+    const manifest = mergeBrowserRuntimeManifests(...manifests);
+    if (manifest.assets.length === 0) {
         return result;
     }
     const moduleRequireFromContext = createRequire(path.join(contextRoot, 'package.json'));
     const fs = moduleRequireFromContext('node:fs');
-    const cacheFingerprint = `${Array.from(specifierMap.entries()).sort().join('|')}`;
+    const cacheFingerprint = manifest.assets
+        .map((asset) => `${asset.specifier}->${asset.publicPath}`)
+        .sort()
+        .join('|');
     for (const output of result.outputs) {
         if (!/\.(?:[cm]?js)$/u.test(output.path)) {
             continue;
@@ -390,7 +395,7 @@ export function rewriteBrowserRuntimeImportsInOutputs(result, contextRoot, plugi
         if (rewriteCache.has(contentKey)) {
             continue;
         }
-        const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, output.path);
+        const rewritten = rewriteBrowserRuntimeImports(code, manifest, output.path);
         if (rewritten !== code) {
             fs.writeFileSync(output.path, rewritten);
         }

package/src/dev/transform-server/dev-transform-import-rewriter.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { fileSystem } from '@ecopages/file-system';
 import { cachedParseSync } from '../../cache/module-parse-cache.js';
 import { isBarePackageImportSpecifier, resolveProjectModulePath } from '../../plugins/tsconfig-import-resolver.js';
+import { resolveRuntimeSpecifierPublicPath } from '../../build/browser/browser-runtime-manifest.js';
 import { resolveDevTransformModuleUrl } from './dev-transform-url.js';
 /**
  * Builds a browser-importable dev-transform URL that changes when the source changes.
@@ -106,7 +107,7 @@ export async function rewriteModuleImports(options) {
     };
 }
 async function resolveImportSpecifier(options) {
-    const runtimeUrl = options.runtimeSpecifierMap.get(options.specifier);
+    const runtimeUrl = resolveRuntimeSpecifierPublicPath(options.specifier, options.runtimeSpecifierMap);
     if (runtimeUrl) {
         return runtimeUrl;
     }

package/src/dev/transform-server/dev-transform-vendor-registry.js

@@ -4,9 +4,17 @@ import { fileSystem } from '@ecopages/file-system';
 import { RESOLVED_ASSETS_VENDORS_DIR } from '../../config/constants.js';
 import { getAppBrowserBuildPlugins } from '../../build/build-adapter.js';
 import { resolveBarePackageBrowserEntry } from '../../plugins/tsconfig-import-resolver.js';
+import { toPackageRootSpecifier } from '../../plugins/package-specifier.js';
+import { resolveRuntimeSpecifierPublicPath } from '../../build/browser/browser-runtime-manifest.js';
 import { BrowserBundleService } from '../../services/assets/browser-bundle.service.js';
-const BROWSER_VENDOR_CONDITIONS = ['browser', 'module', 'import', 'default'];
+const BROWSER_FIRST_VENDOR_CONDITIONS = ['browser', 'module', 'import', 'default'];
+const MODULE_FIRST_VENDOR_CONDITIONS = ['module', 'import', 'default'];
 const BROWSER_NODE_BUILTIN_GUARD_MARKER = '[browser-build] Node builtin';
+function getVendorBundleConditions(specifier) {
+    return toPackageRootSpecifier(specifier) === '@ecopages/core'
+        ? BROWSER_FIRST_VENDOR_CONDITIONS
+        : MODULE_FIRST_VENDOR_CONDITIONS;
+}
 /**
  * Lazily prebundles bare npm imports into cacheable `/assets/vendors/*` chunks.
  */
@@ -27,7 +35,7 @@ export class DevTransformVendorRegistry {
         this.vendorsDir = path.join(distDir, RESOLVED_ASSETS_VENDORS_DIR);
     }
     resolveKnownVendorUrl(specifier) {
-        return this.getRuntimeSpecifierMap().get(specifier);
+        return resolveRuntimeSpecifierPublicPath(specifier, this.getRuntimeSpecifierMap());
     }
     async resolveVendorUrl(specifier) {
         const known = this.resolveKnownVendorUrl(specifier);
@@ -114,7 +122,7 @@ export class DevTransformVendorRegistry {
             externalPackages: false,
             treeshaking: true,
             splitting: false,
-            conditions: [...BROWSER_VENDOR_CONDITIONS],
+            conditions: [...getVendorBundleConditions(specifier)],
             excludeAppBuildPlugins: getAppBrowserBuildPlugins(this.appConfig).map((plugin) => plugin.name),
             plugins: [...vendorPlugins],
         });

package/src/plugins/package-specifier.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalizes bare npm import specifiers to their package root.
+ *
+ * @example
+ * toPackageRootSpecifier('@scope/pkg/sub/file') -> '@scope/pkg'
+ * toPackageRootSpecifier('lodash/debounce') -> 'lodash'
+ */
+export declare function toPackageRootSpecifier(specifier: string): string;
+/**
+ * Returns true when `specifier` is a subpath import of `packageRoot`.
+ */
+export declare function isSubpathOfPackageRoot(specifier: string, packageRoot: string): boolean;

package/src/plugins/package-specifier.js

@@ -0,0 +1,33 @@
+/**
+ * Normalizes bare npm import specifiers to their package root.
+ *
+ * @example
+ * toPackageRootSpecifier('@scope/pkg/sub/file') -> '@scope/pkg'
+ * toPackageRootSpecifier('lodash/debounce') -> 'lodash'
+ */
+export function toPackageRootSpecifier(specifier) {
+    if (specifier.startsWith('.') ||
+        specifier.startsWith('/') ||
+        specifier.startsWith('node:') ||
+        specifier.includes('://')) {
+        return specifier;
+    }
+    if (specifier.startsWith('@')) {
+        const [scope, name, ...rest] = specifier.split('/');
+        if (!scope || !name) {
+            return specifier;
+        }
+        return rest.length > 0 ? `${scope}/${name}` : specifier;
+    }
+    const [name] = specifier.split('/');
+    return name ?? specifier;
+}
+/**
+ * Returns true when `specifier` is a subpath import of `packageRoot`.
+ */
+export function isSubpathOfPackageRoot(specifier, packageRoot) {
+    if (specifier === packageRoot) {
+        return false;
+    }
+    return specifier.startsWith(`${packageRoot}/`);
+}

package/src/plugins/tsconfig-import-resolver.d.ts

@@ -12,9 +12,11 @@ export declare function isBarePackageImportSpecifier(specifier: string, projectR
  * Resolves a bare npm package entry for browser vendor prebundles.
  *
  * @remarks
- * Prefer package `"browser"` / `"exports.browser"` over Node `"import"` entries.
- * `createRequire().resolve()` is wrong here — it selects the server facade for
- * dual packages such as `@ecopages/core`.
+ * Framework-owned dual packages such as `@ecopages/core` keep browser-first
+ * `mainFields` and `conditionNames` so vendor prebundles pick the browser facade.
+ * Third-party packages prefer ESM (`module` / `import`) and omit the `browser`
+ * export condition so legacy UMD `exports.browser` entries cannot win during
+ * Rolldown bundling.
  */
 export declare function resolveBarePackageBrowserEntry(projectRoot: string, specifier: string): string | undefined;
 /**

package/src/plugins/tsconfig-import-resolver.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { ResolverFactory } from 'oxc-resolver';
+import { toPackageRootSpecifier } from './package-specifier.js';
 const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mdx'];
 const resolverCache = new Map();
 const pathPrefixCache = new Map();
@@ -111,33 +112,59 @@ function getResolverFactory(projectRoot) {
     resolverCache.set(projectRoot, resolver);
     return resolver;
 }
-const BROWSER_PACKAGE_CONDITION_NAMES = ['browser', 'module', 'import', 'default'];
-const BROWSER_PACKAGE_MAIN_FIELDS = ['browser', 'module', 'main'];
+const BROWSER_FIRST_CONDITION_NAMES = ['browser', 'module', 'import', 'default'];
+/**
+ * Omit `browser` so package `exports` cannot select a legacy UMD facade when both
+ * `browser` and `import` conditions are published. Legacy `mainFields.browser`
+ * remains available after `module` for packages without `exports`.
+ */
+const MODULE_FIRST_CONDITION_NAMES = ['module', 'import', 'default'];
+const BROWSER_FIRST_MAIN_FIELDS = ['browser', 'module', 'main'];
+const MODULE_FIRST_MAIN_FIELDS = ['module', 'browser', 'main'];
+/**
+ * Package roots that ship an explicit browser facade and must keep browser-first
+ * resolution during vendor prebundles.
+ *
+ * @remarks
+ * Prefer expanding this set only for dual packages whose `"browser"` / `exports.browser`
+ * entry is the intentional client facade (for example `@ecopages/core`).
+ */
+const BROWSER_FIRST_PACKAGE_ROOTS = new Set(['@ecopages/core']);
 const browserPackageResolvers = new Map();
-function getBrowserPackageResolver(projectRoot) {
+function usesBrowserFirstPackageResolution(specifier) {
+    const packageRoot = toPackageRootSpecifier(specifier);
+    return BROWSER_FIRST_PACKAGE_ROOTS.has(packageRoot);
+}
+function getBrowserPackageResolver(projectRoot, mainFields, conditionNames) {
     const normalizedRoot = path.resolve(projectRoot);
-    const cached = browserPackageResolvers.get(normalizedRoot);
+    const cacheKey = `${normalizedRoot}\0${mainFields.join(',')}\0${conditionNames.join(',')}`;
+    const cached = browserPackageResolvers.get(cacheKey);
     if (cached) {
         return cached;
     }
     const resolver = new ResolverFactory({
-        conditionNames: [...BROWSER_PACKAGE_CONDITION_NAMES],
-        mainFields: [...BROWSER_PACKAGE_MAIN_FIELDS],
+        conditionNames: [...conditionNames],
+        mainFields: [...mainFields],
         extensions: [...RESOLVABLE_EXTENSIONS],
     });
-    browserPackageResolvers.set(normalizedRoot, resolver);
+    browserPackageResolvers.set(cacheKey, resolver);
     return resolver;
 }
 /**
  * Resolves a bare npm package entry for browser vendor prebundles.
  *
  * @remarks
- * Prefer package `"browser"` / `"exports.browser"` over Node `"import"` entries.
- * `createRequire().resolve()` is wrong here — it selects the server facade for
- * dual packages such as `@ecopages/core`.
+ * Framework-owned dual packages such as `@ecopages/core` keep browser-first
+ * `mainFields` and `conditionNames` so vendor prebundles pick the browser facade.
+ * Third-party packages prefer ESM (`module` / `import`) and omit the `browser`
+ * export condition so legacy UMD `exports.browser` entries cannot win during
+ * Rolldown bundling.
  */
 export function resolveBarePackageBrowserEntry(projectRoot, specifier) {
-    const result = getBrowserPackageResolver(projectRoot).sync(projectRoot, specifier);
+    const browserFirst = usesBrowserFirstPackageResolution(specifier);
+    const mainFields = browserFirst ? BROWSER_FIRST_MAIN_FIELDS : MODULE_FIRST_MAIN_FIELDS;
+    const conditionNames = browserFirst ? BROWSER_FIRST_CONDITION_NAMES : MODULE_FIRST_CONDITION_NAMES;
+    const result = getBrowserPackageResolver(projectRoot, mainFields, conditionNames).sync(projectRoot, specifier);
     if (result.error || !result.path) {
         return undefined;
     }

package/src/route-renderer/orchestration/route-pipeline/route-prepared-options.builder.js

@@ -5,7 +5,7 @@ import { createPageLocalsProxy } from './route-prepared-options.utils.js';
  * Assembles the final integration render options after route prep dependencies resolve.
  */
 export function buildPreparedRenderOptions(input) {
-    const { routeOptions, resolvedInputs, resolvedPageDependencyComponents, resolvedDependencies, allDependencies, pageBrowserGraph, appConfig, } = input;
+    const { routeOptions, resolvedInputs, resolvedPageDependencyComponents, resolvedDependencies, allDependencies, pageBrowserGraph, } = input;
     const { Page, HtmlTemplate, Layouts, Layout, layoutEntries, props, metadata, integrationSpecificProps } = resolvedInputs;
     const dedupedDependencies = dedupeProcessedAssets(allDependencies);
     const pagePackage = createPagePackage(dedupedDependencies, { pageBrowserGraph });
@@ -16,13 +16,8 @@ export function buildPreparedRenderOptions(input) {
         query: routeOptions.query || {},
     };
     const cacheStrategy = Page.cache;
-    const defaultCacheStrategy = appConfig.cache?.defaultStrategy ?? 'static';
-    const effectiveCacheStrategy = cacheStrategy ?? defaultCacheStrategy;
-    const localsAvailable = effectiveCacheStrategy === 'dynamic' && routeOptions.locals !== undefined;
-    const pageLocals = localsAvailable
-        ? routeOptions.locals
-        : createPageLocalsProxy(routeOptions.file);
-    const locals = localsAvailable ? routeOptions.locals : undefined;
+    const pageLocals = routeOptions.locals ?? createPageLocalsProxy(routeOptions.file);
+    const locals = routeOptions.locals;
     const preparedOptions = {
         ...routeOptions,
         resolvedPageDependencyComponents,

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

@@ -89,6 +89,11 @@ export declare class AssetProcessingService {
      * Stores one processed asset in the dependency cache.
      */
     private setCachedAsset;
+    /**
+     * Removes a cached asset and advances the development HTML cache generation
+     * when the removed asset can determine browser runtime URLs.
+     */
+    private invalidateCachedAsset;
     private getFileSourceHash;
     /**
      * Clears all cached processed assets.

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

@@ -9,6 +9,7 @@ import { isHmrAware } from './processor.interface.js';
 import { ProcessorRegistry } from './processor.registry.js';
 import { processUngroupedDependency } from './ungrouped-dependency-processing.js';
 import { materializeContentScriptAsset } from './materialize-content-script-asset.js';
+import { bumpBrowserRuntimeAssetGeneration } from '../browser-runtime-asset-generation.js';
 import { ContentScriptProcessor, ContentStylesheetProcessor, FileScriptProcessor, FileStylesheetProcessor, NodeModuleScriptProcessor, } from './processors/index.js';
 /**
  * Processes declared component and page asset dependencies for one app instance.
@@ -234,7 +235,7 @@ export class AssetProcessingService {
         }
         const sourceHash = this.getFileSourceHash(dep);
         if (dep.source === 'file' && sourceHash === undefined) {
-            this.cache.delete(depKey);
+            this.invalidateCachedAsset(depKey);
             return null;
         }
         const cached = this.cache.get(depKey);
@@ -242,11 +243,11 @@ export class AssetProcessingService {
             return null;
         }
         if (cached.sourceHash !== sourceHash) {
-            this.cache.delete(depKey);
+            this.invalidateCachedAsset(depKey);
             return null;
         }
         if (cached.asset.filepath && !fileSystem.exists(cached.asset.filepath)) {
-            this.cache.delete(depKey);
+            this.invalidateCachedAsset(depKey);
             return null;
         }
         return cached.asset;
@@ -275,10 +276,26 @@ export class AssetProcessingService {
      * Stores one processed asset in the dependency cache.
      */
     setCachedAsset(dep, depKey, asset) {
+        const previous = this.cache.get(depKey)?.asset;
+        const tracksBrowserRuntimeGeneration = dep.packageRole === 'runtime' || dep.packageRole === 'page-script';
         this.cache.set(depKey, {
             asset,
             sourceHash: this.getFileSourceHash(dep),
         });
+        if (tracksBrowserRuntimeGeneration && previous !== undefined && previous.filepath !== asset.filepath) {
+            void bumpBrowserRuntimeAssetGeneration(this.config);
+        }
+    }
+    /**
+     * Removes a cached asset and advances the development HTML cache generation
+     * when the removed asset can determine browser runtime URLs.
+     */
+    invalidateCachedAsset(depKey) {
+        const cached = this.cache.get(depKey);
+        this.cache.delete(depKey);
+        if (cached?.asset.packageRole === 'runtime' || cached?.asset.packageRole === 'page-script') {
+            void bumpBrowserRuntimeAssetGeneration(this.config);
+        }
     }
     getFileSourceHash(dep) {
         if (dep.source !== 'file' || !('filepath' in dep) || !fileSystem.exists(dep.filepath)) {
@@ -290,19 +307,29 @@ export class AssetProcessingService {
      * Clears all cached processed assets.
      */
     clearCache() {
+        const invalidatesBrowserRuntime = Array.from(this.cache.values()).some(({ asset }) => asset.packageRole === 'runtime' || asset.packageRole === 'page-script');
         this.cache.clear();
+        if (invalidatesBrowserRuntime) {
+            void bumpBrowserRuntimeAssetGeneration(this.config);
+        }
     }
     /**
      * Removes cached assets that were produced from the given file path.
      */
     invalidateCacheForFile(filepath) {
+        let invalidatesBrowserRuntime = false;
         for (const [key, value] of this.cache.entries()) {
             if (value.asset.filepath === filepath ||
                 value.asset.sourceFilepath === filepath ||
                 value.asset.bundledSourceFilepaths?.includes(filepath)) {
+                invalidatesBrowserRuntime ||=
+                    value.asset.packageRole === 'runtime' || value.asset.packageRole === 'page-script';
                 this.cache.delete(key);
             }
         }
+        if (invalidatesBrowserRuntime) {
+            void bumpBrowserRuntimeAssetGeneration(this.config);
+        }
     }
     /**
      * Creates a service prewired with the default core processors.

package/src/services/assets/browser-runtime-asset-generation.d.ts

@@ -0,0 +1,17 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Returns the current browser-runtime asset generation for one app.
+ *
+ * @remarks
+ * Development HTML caches include this generation so rebuilt bootstrap and
+ * vendor URLs cannot leave stale script references behind.
+ */
+export declare function getBrowserRuntimeAssetGeneration(appConfig: EcoPagesAppConfig): number;
+/**
+ * Bumps browser-runtime asset generation and clears rendered HTML cache entries.
+ *
+ * @remarks
+ * Only call this when a previously cached runtime/page-script asset filepath changes.
+ * First inserts must not bump generation or cold start thrash-clears the HTML cache.
+ */
+export declare function bumpBrowserRuntimeAssetGeneration(appConfig: EcoPagesAppConfig): Promise<void>;

package/src/services/assets/browser-runtime-asset-generation.js

@@ -0,0 +1,28 @@
+import { clearAppPageCache } from '../cache/page-cache-service.js';
+import { isDevelopmentRuntime } from '../../utils/runtime.js';
+const generationByAppConfig = new WeakMap();
+/**
+ * Returns the current browser-runtime asset generation for one app.
+ *
+ * @remarks
+ * Development HTML caches include this generation so rebuilt bootstrap and
+ * vendor URLs cannot leave stale script references behind.
+ */
+export function getBrowserRuntimeAssetGeneration(appConfig) {
+    return generationByAppConfig.get(appConfig) ?? 0;
+}
+/**
+ * Bumps browser-runtime asset generation and clears rendered HTML cache entries.
+ *
+ * @remarks
+ * Only call this when a previously cached runtime/page-script asset filepath changes.
+ * First inserts must not bump generation or cold start thrash-clears the HTML cache.
+ */
+export async function bumpBrowserRuntimeAssetGeneration(appConfig) {
+    if (!isDevelopmentRuntime()) {
+        return;
+    }
+    const nextGeneration = getBrowserRuntimeAssetGeneration(appConfig) + 1;
+    generationByAppConfig.set(appConfig, nextGeneration);
+    await clearAppPageCache(appConfig);
+}

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

@@ -10,7 +10,8 @@ import type { CacheStrategy, RenderResult } from './cache.types.js';
 export declare class PageRequestCacheCoordinator {
     private cacheService;
     private defaultCacheStrategy;
-    constructor(cacheService: PageCacheService | null, defaultCacheStrategy: CacheStrategy);
+    private readonly getRuntimeAssetGeneration?;
+    constructor(cacheService: PageCacheService | null, defaultCacheStrategy: CacheStrategy, getRuntimeAssetGeneration?: () => number);
     /**
      * Builds the cache key used for page lookups.
      *

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

@@ -1,5 +1,6 @@
 import { getCacheControlHeader } from './page-cache-service.js';
 import { getRequestPipelineMetricsHeaderName, isRequestPipelineMetricsEnabled, serializeRequestPipelineMetricsHeader, } from '../../diagnostics/request-pipeline-metrics.js';
+import { isDevelopmentRuntime } from '../../utils/runtime.js';
 /**
  * Coordinates request-time page caching concerns around one render invocation.
  *
@@ -10,9 +11,11 @@ import { getRequestPipelineMetricsHeaderName, isRequestPipelineMetricsEnabled, s
 export class PageRequestCacheCoordinator {
     cacheService;
     defaultCacheStrategy;
-    constructor(cacheService, defaultCacheStrategy) {
+    getRuntimeAssetGeneration;
+    constructor(cacheService, defaultCacheStrategy, getRuntimeAssetGeneration) {
         this.cacheService = cacheService;
         this.defaultCacheStrategy = defaultCacheStrategy;
+        this.getRuntimeAssetGeneration = getRuntimeAssetGeneration;
     }
     /**
      * Builds the cache key used for page lookups.
@@ -29,6 +32,9 @@ export class PageRequestCacheCoordinator {
             const queryString = new URLSearchParams(input.query).toString();
             key += `?${queryString}`;
         }
+        if (this.getRuntimeAssetGeneration && isDevelopmentRuntime()) {
+            key += `#__eco_rt=${this.getRuntimeAssetGeneration()}`;
+        }
         return key;
     }
     /**

package/src/services/invalidation/development-invalidation.service.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { getAppServerInvalidationState } from '../runtime-state/server-invalidation-state.service.js';
 import { appLogger } from '../../global/app-logger.js';
+import { clearAppDevelopmentRouteModuleBuildCaches } from '../module-loading/route-module-build-cache-registry.js';
 /**
  * Framework-owned development invalidation service.
  *
@@ -29,6 +30,7 @@ export class DevelopmentInvalidationService {
     invalidateServerModules(changedFiles) {
         getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
         this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
+        clearAppDevelopmentRouteModuleBuildCaches(this.appConfig);
     }
     /**
      * Registers an integration-owned handler for registered script entrypoint edits.
@@ -57,8 +59,8 @@ export class DevelopmentInvalidationService {
      * Resets runtime-owned graph state and invalidates server modules.
      */
     resetRuntimeState(changedFiles) {
+        this.invalidateServerModules(changedFiles);
         const serverInvalidationState = getAppServerInvalidationState(this.appConfig);
-        serverInvalidationState.invalidateServerModules(changedFiles);
         serverInvalidationState.reset();
     }
     /**

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

@@ -33,7 +33,7 @@ Call site (route scan, renderer, SSG, API)
 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.
+Development import URLs use `sourceHash` plus a per-service import generation counter. Node uses that value in its `?update=` query. Bun also receives a generation-specific compiled output filename because it retains a previously imported file when only its query changes. Both paths advance after `invalidateDevelopmentGraph()` without a process-wide invalidation version in reuse keys.
 
 ## Files
 
@@ -49,4 +49,4 @@ Development `?update=` query params use `sourceHash` plus a per-service import g
 
 ## Development invalidation
 
-`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.
+`DevelopmentInvalidationService.invalidateServerModules()` calls `appModuleLoader.invalidateDevelopmentGraph()`, which clears the in-memory import cache, bumps the per-service dev import generation used for runtime URLs and Bun output filenames, and clears dependency-hash memoization. It also clears persisted route-module entries: externalized generated modules can change without appearing in a route bundle's dependency graph, so retaining those entries could reload stale server HTML.

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

@@ -127,10 +127,7 @@ export class PageModuleImportService {
     async loadModule(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,
-        });
+        const outputFileName = createRuntimeBuildOutputFileName(resolvePageModuleOutputFileName({ filePath, fileHash }), this.developmentImportGeneration);
         const outputNamingTemplate = outputFileName.replace(/\.mjs$/u, '.[ext]');
         const preferredOutputPath = path.join(outdir, outputFileName);
         const buildOptions = this.appConfig
@@ -229,3 +226,17 @@ function createRuntimeModuleUrl(filePath, fileHash, developmentImportGeneration)
 function shouldAddRuntimeUpdateQuery() {
     return process.env.NODE_ENV === 'development';
 }
+/**
+ * Gives Bun a distinct compiled module path after development invalidation.
+ *
+ * @remarks
+ * Bun does not reload an already-imported module when only its URL query changes.
+ * A dependency edit can leave the entrypoint source hash unchanged, so the output
+ * filename must include the import generation as well as the runtime query.
+ */
+function createRuntimeBuildOutputFileName(outputFileName, developmentImportGeneration) {
+    if (typeof Bun === 'undefined' || !shouldAddRuntimeUpdateQuery()) {
+        return outputFileName;
+    }
+    return outputFileName.replace(/\.mjs$/u, `-${developmentImportGeneration}.mjs`);
+}

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

@@ -22,3 +22,5 @@ export declare const getRouteModuleBuildCacheOutdir: typeof getServerModuleBuild
  * generation during the same build process.
  */
 export declare function getSharedRouteModuleBuildCache(outdir: string, appConfig?: EcoPagesAppConfig): RouteModuleBuildCache;
+/** Clears route-module cache entries that can retain stale external server modules during development. */
+export declare function clearAppDevelopmentRouteModuleBuildCaches(appConfig: EcoPagesAppConfig): void;

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

@@ -49,3 +49,15 @@ export function getSharedRouteModuleBuildCache(outdir, appConfig) {
     caches.set(outdir, routeModuleBuildCache);
     return routeModuleBuildCache;
 }
+/** Clears route-module cache entries that can retain stale external server modules during development. */
+export function clearAppDevelopmentRouteModuleBuildCaches(appConfig) {
+    const serverModuleCacheOutdir = getServerModuleBuildCacheOutdir(appConfig);
+    const caches = appConfig.runtime?.routeModuleBuildCaches;
+    const serverModuleCache = caches?.get(serverModuleCacheOutdir) ?? new RouteModuleBuildCache(serverModuleCacheOutdir);
+    serverModuleCache.clearDevelopmentEntries();
+    for (const cache of caches?.values() ?? []) {
+        if (cache !== serverModuleCache) {
+            cache.clearDevelopmentEntries();
+        }
+    }
+}

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

@@ -51,6 +51,16 @@ export declare class RouteModuleBuildCache {
         context: RouteModuleStaticRenderCacheContext;
     }): void;
     resetMemory(): void;
+    /**
+     * Removes every persisted route-module entry after development invalidation.
+     *
+     * @remarks
+     * Server bundles may externalize generated modules whose source dependencies
+     * are not present in the route bundle's dependency graph. Keeping an entry
+     * after its server graph changes can therefore reload a route that still
+     * imports an obsolete external bundle.
+     */
+    clearDevelopmentEntries(): void;
     pruneStaleRenderedOutputs(activePathnames: ReadonlySet<string>): string[];
     private loadManifest;
     private persistManifest;

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

@@ -164,6 +164,24 @@ export class RouteModuleBuildCache {
         this.manifest = undefined;
         this.manifestLoaded = false;
     }
+    /**
+     * Removes every persisted route-module entry after development invalidation.
+     *
+     * @remarks
+     * Server bundles may externalize generated modules whose source dependencies
+     * are not present in the route bundle's dependency graph. Keeping an entry
+     * after its server graph changes can therefore reload a route that still
+     * imports an obsolete external bundle.
+     */
+    clearDevelopmentEntries() {
+        if (!this.manifestLoaded && !this.dependencies.exists(this.manifestPath)) {
+            return;
+        }
+        const manifest = createEmptyRouteModuleBuildCacheManifest();
+        this.manifest = manifest;
+        this.manifestLoaded = true;
+        this.persistManifest(manifest);
+    }
     pruneStaleRenderedOutputs(activePathnames) {
         if (process.env.NODE_ENV !== 'production') {
             return [];

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

@@ -646,8 +646,9 @@ export type EcoLayoutComponent<T = EcoPagesElement> = EcoComponent<LayoutProps<T
 export type EcoHtmlComponent<T = EcoPagesElement> = EcoComponent<HtmlTemplateProps, T>;
 /**
  * Props type for the semantic `404.*` page template.
- * @remarks `message` and `stack` are declared for future error context. The
- * runtime does not currently pass these props when rendering the custom 404 page.
+ * @remarks Semantic error templates receive safe empty `pageLocals` rather than
+ * request-scoped locals. The runtime does not currently pass `message` / `stack`
+ * when rendering the custom 404 page.
  */
 export interface Error404TemplateProps extends Omit<HtmlTemplateProps, 'children'> {
     message: string;
@@ -658,7 +659,8 @@ export interface Error404TemplateProps extends Omit<HtmlTemplateProps, 'children
  * @remarks In development, the page-pipeline passes `message` and `stack` from the
  * thrown error when rendering this page after a failure. In production those
  * fields are omitted so stacks are not serialized into HTML. Direct visits to
- * `/500` also omit them.
+ * `/500` also omit them. Semantic error templates receive safe empty
+ * `pageLocals` rather than request-scoped locals.
  */
 export interface Error500TemplateProps extends Omit<HtmlTemplateProps, 'children'> {
     message?: string;