@ecopages/core 0.2.0-beta.26 → 0.2.0-beta.28

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

@@ -1,6 +1,4 @@
-import { getAppServerBuildPlugins } from "../../build/build-adapter.js";
-import { requireBuildRuntime } from "../../build/build-runtime.js";
-import { getJsxOwnershipPlugins } from "../../build/jsx-ownership-plugins.js";
+import { requireBuildRuntime } from "../../build/runtime/build-runtime.js";
 import path from "node:path";
 import { DevelopmentInvalidationService } from "../invalidation/development-invalidation.service.js";
 import {} from "./app-module-loader.service.js";
@@ -44,8 +42,6 @@ function createAppModuleLoader(appConfig) {
     canLoadSourceModuleFromHost: (filePath) => shouldAppUseHostModuleLoader(appConfig, filePath),
     getHostModuleLoader: () => getAppHostModuleLoader(appConfig)
   });
-  const appServerBuildPlugins = appConfig.runtime?.buildManifest ? getAppServerBuildPlugins(appConfig) : Array.from(appConfig.loaders?.values() ?? []);
-  const jsxOwnershipPlugins = getJsxOwnershipPlugins(appConfig);
   const appModuleLoader = {
     get owner() {
       return getAppModuleLoaderOwner(appConfig);
@@ -53,10 +49,8 @@ function createAppModuleLoader(appConfig) {
     pageModuleImportService,
     async importModule(options) {
       const invalidationVersion = options.invalidationVersion ?? invalidationService.getServerModuleInvalidationVersion();
-      const mergedPlugins = [...appServerBuildPlugins, ...jsxOwnershipPlugins, ...options.plugins ?? []];
       return await pageModuleImportService.importModule({
         ...options,
-        ...mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {},
         buildExecutor: options.buildExecutor ?? requireBuildRuntime(appConfig).getProfile("route-module"),
         invalidationVersion
       });

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

@@ -1,5 +1,5 @@
 import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../../build/build-types.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 {

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

@@ -2,19 +2,16 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { fileSystem } from "@ecopages/file-system";
 import { build } from "../../build/build-adapter.js";
-import { resolveBuildProfileOptions } from "../../build/build-profile-options.js";
-import { normalizeNodeRuntimeBuildOutputFile } from "../../build/runtime-build-output-normalizer.js";
+import { createServerBuildRequest } from "../../build/runtime/build-request-policy.js";
+import { resolveBuildProfileOptions } from "../../build/runtime/build-profile-options.js";
 import {
   importPagesUnifiedGraphModule,
   isPagesUnifiedGraphPage,
   shouldBuildPagesUnifiedGraph
-} from "../../build/pages-unified-graph-build.js";
-import { recordPageModuleBuildInvocation } from "../../build/rolldown-build-invocation-metrics.js";
-import {
-  resolvePageModuleOutputFileName,
-  createPluginCacheKey,
-  createJsxCacheKey
-} from "./route-module-build-cache.js";
+} from "../../build/cache/pages-unified-graph-build.js";
+import { recordPageModuleBuildInvocation } from "../../build/rolldown/rolldown-build-invocation-metrics.js";
+import { resolvePageModuleOutputFileName } from "./route-module-build-cache.js";
+import { createPluginCacheKey, createJsxCacheKey } from "../../build/cache/cache-keys.js";
 import { getSharedRouteModuleBuildCache } from "./route-module-build-cache-registry.js";
 import {
   RouteModuleDependencyHasher,
@@ -151,11 +148,41 @@ class PageModuleImportService {
     });
     const outputNamingTemplate = outputFileName.replace(/\.mjs$/u, ".[ext]");
     const preferredOutputPath = path.join(outdir, outputFileName);
-    const routeModuleBuildCache = this.getRouteModuleBuildCache(outdir);
-    const cachedBuild = routeModuleBuildCache.lookup({
+    const buildOptions = this.appConfig ? createServerBuildRequest(this.appConfig, {
+      profile: "route-module",
+      entrypoints: [filePath],
+      outdir,
+      naming: outputNamingTemplate,
+      splitting: splitting ?? true,
+      jsx: options.jsx,
+      plugins: options.plugins,
+      root: rootDir,
+      ...externalPackages !== void 0 ? { externalPackages } : {}
+    }) : {
+      ...resolveBuildProfileOptions("route-module", { rootDir }, {
+        entrypoints: [filePath],
+        outdir,
+        naming: outputNamingTemplate,
+        splitting: splitting ?? true,
+        jsx: options.jsx,
+        plugins: options.plugins,
+        ...externalPackages !== void 0 ? { externalPackages } : {}
+      }),
+      root: rootDir,
+      entrypoints: [filePath]
+    };
+    const cacheBuildOptions = {
       ...options,
+      rootDir: buildOptions.root ?? rootDir,
+      outdir: buildOptions.outdir ?? outdir,
+      splitting: buildOptions.splitting,
+      externalPackages: buildOptions.externalPackages,
+      jsx: buildOptions.jsx,
+      plugins: buildOptions.plugins,
       fileHash
-    });
+    };
+    const routeModuleBuildCache = this.getRouteModuleBuildCache(outdir);
+    const cachedBuild = routeModuleBuildCache.lookup(cacheBuildOptions);
     if (cachedBuild) {
       return await import(
         /* @vite-ignore */
@@ -169,19 +196,6 @@ class PageModuleImportService {
       }
     }
     recordPageModuleBuildInvocation();
-    const buildOptions = {
-      ...resolveBuildProfileOptions("route-module", this.appConfig ?? { rootDir }, {
-        entrypoints: [filePath],
-        outdir,
-        naming: outputNamingTemplate,
-        splitting: splitting ?? true,
-        jsx: options.jsx,
-        plugins: options.plugins,
-        ...externalPackages !== void 0 ? { externalPackages } : {}
-      }),
-      root: rootDir,
-      entrypoints: [filePath]
-    };
     const buildResult = await this.dependencies.buildModule(buildOptions, options.buildExecutor);
     if (!buildResult.success) {
       const details = buildResult.logs.map((log) => log.message).join(" | ");
@@ -191,7 +205,6 @@ class PageModuleImportService {
     if (!compiledOutput) {
       throw new Error(noOutputMessage(filePath));
     }
-    normalizeNodeRuntimeBuildOutputFile(compiledOutput, rootDir);
     const dependencyModulePaths = resolveRouteModuleDependencyPaths(buildResult, filePath, rootDir);
     const dependencyHashes = this.dependencyHasher.createDependencyHashes(dependencyModulePaths);
     dependencyHashes[path.normalize(filePath)] = fileHash;
@@ -202,8 +215,7 @@ class PageModuleImportService {
       }
     }
     routeModuleBuildCache.recordBuild({
-      ...options,
-      fileHash,
+      ...cacheBuildOptions,
       outputPath: compiledOutput,
       dependencyModulePaths
     });

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

@@ -14,7 +14,7 @@ import {
 import {
   isProductionCacheManifestCurrent,
   matchesProductionCacheFingerprint
-} from "../../build/production-build-cache.js";
+} from "../../build/cache/production-build-cache.js";
 class RouteModuleBuildCache {
   manifestPath;
   dependencies;

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

@@ -1,8 +1,7 @@
-import type { EcoBuildPlugin } from '../../build/build-types.js';
 import type { PageModuleBuildImportOptions } from './page-module-import.service.js';
 import type { RouteModuleDependencyHashes } from './route-module-dependency-hasher.js';
-/** Filename written beside transpiled server modules that stores incremental build metadata. */
-export declare const ROUTE_MODULE_BUILD_CACHE_FILENAME = ".build-cache.json";
+export { createJsxCacheKey, createPluginCacheKey, getCorePackageVersion, hashPluginSetup, } from '../../build/cache/cache-keys.js';
+export { ROUTE_MODULE_BUILD_CACHE_FILENAME } from '../../build/cache/cache-constants.js';
 /** One persisted route-module build entry in {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}. */
 export interface RouteModuleBuildCacheEntry {
     sourceHash: string;
@@ -37,8 +36,6 @@ export interface RouteModuleStaticRenderCacheContext {
 }
 export type RouteModuleBuildCacheManifestReader = (manifestPath: string) => RouteModuleBuildCacheManifest | undefined;
 export type RouteModuleBuildCacheManifestWriter = (manifestPath: string, manifest: RouteModuleBuildCacheManifest) => void;
-/** Returns the installed `@ecopages/core` package version used to invalidate persisted caches. */
-export declare function getCorePackageVersion(): string;
 /** 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. */
@@ -55,7 +52,3 @@ export declare function createPersistedRouteModuleBuildKey(options: PageModuleBu
 export declare function createEmptyRouteModuleBuildCacheManifest(): RouteModuleBuildCacheManifest;
 export declare function readRouteModuleBuildCacheManifest(manifestPath: string): RouteModuleBuildCacheManifest | undefined;
 export declare function writeRouteModuleBuildCacheManifest(manifestPath: string, manifest: RouteModuleBuildCacheManifest): void;
-export declare function createJsxCacheKey(jsx: PageModuleBuildImportOptions['jsx']): string;
-export declare function createPluginCacheKey(plugins?: EcoBuildPlugin[]): string;
-/** Exported for in-process import caches that must match persisted build keys. */
-export declare function hashPluginSetup(setup: EcoBuildPlugin['setup']): string;

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

@@ -1,17 +1,13 @@
-import { readFileSync } from "node:fs";
 import path from "node:path";
-import { readProductionCacheManifest, writeProductionCacheManifest } from "../../build/production-build-cache.js";
-const ROUTE_MODULE_BUILD_CACHE_FILENAME = ".build-cache.json";
-let cachedCorePackageVersion;
-function getCorePackageVersion() {
-  if (cachedCorePackageVersion) {
-    return cachedCorePackageVersion;
-  }
-  const packageJsonPath = new URL("../../../package.json", import.meta.url);
-  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-  cachedCorePackageVersion = packageJson.version ?? "0.0.0";
-  return cachedCorePackageVersion;
-}
+import { readProductionCacheManifest, writeProductionCacheManifest } from "../../build/cache/production-build-cache.js";
+import { createJsxCacheKey, createPluginCacheKey, getCorePackageVersion } from "../../build/cache/cache-keys.js";
+import {
+  createJsxCacheKey as createJsxCacheKey2,
+  createPluginCacheKey as createPluginCacheKey2,
+  getCorePackageVersion as getCorePackageVersion2,
+  hashPluginSetup
+} from "../../build/cache/cache-keys.js";
+import { ROUTE_MODULE_BUILD_CACHE_FILENAME } from "../../build/cache/cache-constants.js";
 function normalizeRouteModuleCachePath(filePath) {
   return path.resolve(filePath);
 }
@@ -73,40 +69,13 @@ function shouldVersionBuildOutputPath(invalidationVersion) {
 function sanitizeCacheScope(cacheScope) {
   return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
 }
-function createJsxCacheKey(jsx) {
-  if (!jsx) {
-    return "jsx:default";
-  }
-  return JSON.stringify({
-    development: jsx.development ?? false,
-    factory: jsx.factory ?? null,
-    fragment: jsx.fragment ?? null,
-    importSource: jsx.importSource ?? null,
-    runtime: jsx.runtime ?? null,
-    sideEffects: jsx.sideEffects ?? null
-  });
-}
-function createPluginCacheKey(plugins) {
-  if (!plugins || plugins.length === 0) {
-    return "plugins:default";
-  }
-  return `plugins:${plugins.map((plugin) => `${plugin.name}:${hashPluginSetup(plugin.setup)}`).join(",")}`;
-}
-function hashPluginSetup(setup) {
-  let hash = 0;
-  const source = setup.toString();
-  for (let index = 0; index < source.length; index += 1) {
-    hash = hash * 31 + source.charCodeAt(index) | 0;
-  }
-  return (hash >>> 0).toString(36);
-}
 export {
   ROUTE_MODULE_BUILD_CACHE_FILENAME,
   createEmptyRouteModuleBuildCacheManifest,
-  createJsxCacheKey,
+  createJsxCacheKey2 as createJsxCacheKey,
   createPersistedRouteModuleBuildKey,
-  createPluginCacheKey,
-  getCorePackageVersion,
+  createPluginCacheKey2 as createPluginCacheKey,
+  getCorePackageVersion2 as getCorePackageVersion,
   hashPluginSetup,
   normalizeRouteModuleCachePath,
   readRouteModuleBuildCacheManifest,

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

@@ -1,5 +1,5 @@
 import type { BuildExecutor } from '../../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
 import type { AppModuleLoader } from './app-module-loader.service.js';
 import { type PageModuleBuildImportOptions } from './page-module-import.service.js';
 import type { SourceModuleLoaderFactory } from './module-loading-types.js';

package/src/static-site-generator/README.md

@@ -33,7 +33,7 @@ It should not invent a parallel rendering stack just for build mode.
 | `static-export-context.ts`     | Hook context type for `beforeStaticExport` / `afterStaticExport`             |
 | `static-build-invalidation.ts` | `dist/` reset policy, production cache clearing, static-render cache context |
 
-Build-input fingerprinting (`hashAppConfigFile`, `createBuildInputsFingerprint`) lives in `packages/core/src/build/build-input-fingerprint.ts` and is shared with server-entry and unified-graph caches.
+Build-input fingerprinting (`hashAppConfigFile`, `createBuildInputsFingerprint`) lives in `packages/core/src/build/cache/build-input-fingerprint.ts` and is shared with server-entry and unified-graph caches.
 
 ## Incremental static export
 

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

@@ -0,0 +1,28 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { PageRendererResolver } from '../route-renderer/route-renderer.js';
+/**
+ * Returns whether production static export should warm Page Browser Graphs before rendering.
+ *
+ * @remarks
+ * True only when `NODE_ENV === 'production'`. Independent of `force` and of
+ * unified pages-graph env flags. Does not persist a disk manifest.
+ */
+export declare function shouldPrebuildProductionPageBrowserGraphs(): boolean;
+/**
+ * Clears in-memory production Page Browser Graph session records.
+ *
+ * @remarks
+ * Clears only the `'production'` policy so a failed or force export cannot
+ * reuse staged graph output. Development session records are left intact.
+ */
+export declare function clearProductionPageBrowserGraphSession(appConfig: EcoPagesAppConfig): void;
+/**
+ * Warms production Page Browser Graphs for the supplied static route files.
+ *
+ * @remarks
+ * Deduplicates and lexicographically sorts absolute route paths, then calls
+ * each integration renderer's `prebuildProductionPageBrowserGraph` sequentially
+ * (activates integration runtime, then resolves into
+ * `page-browser-graph-session`). Does not persist a disk manifest.
+ */
+export declare function prebuildProductionPageBrowserGraphs(routeFiles: readonly string[], routeRendererFactory: PageRendererResolver): Promise<void>;

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

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { getAppPageBrowserGraphSession } from "../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js";
+function shouldPrebuildProductionPageBrowserGraphs() {
+  return process.env.NODE_ENV === "production";
+}
+function clearProductionPageBrowserGraphSession(appConfig) {
+  getAppPageBrowserGraphSession(appConfig).clearPolicyRecords("production");
+}
+async function prebuildProductionPageBrowserGraphs(routeFiles, routeRendererFactory) {
+  const uniqueRouteFiles = [...new Set(routeFiles.map((routeFile) => path.resolve(routeFile)))].sort(
+    (left, right) => left.localeCompare(right)
+  );
+  for (const routeFile of uniqueRouteFiles) {
+    const renderer = routeRendererFactory.getPageRenderer(routeFile);
+    await renderer.prebuildProductionPageBrowserGraph(routeFile);
+  }
+}
+export {
+  clearProductionPageBrowserGraphSession,
+  prebuildProductionPageBrowserGraphs,
+  shouldPrebuildProductionPageBrowserGraphs
+};

package/src/static-site-generator/static-build-invalidation.d.ts

@@ -1,7 +1,7 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import { type RouteModuleStaticRenderCacheContext } from '../services/module-loading/route-module-build-manifest.js';
-export type { BuildInputChangeContributor, IntegrationPlugin, Processor } from '../build/build-input-fingerprint.js';
-export { collectBuildInputContributors, createBuildInputsFingerprint, didBuildInputContributorChange, hashAppConfigFile, haveBuildInputsChanged, } from '../build/build-input-fingerprint.js';
+export type { BuildInputChangeContributor, IntegrationPlugin, Processor, } from '../build/cache/build-input-fingerprint.js';
+export { collectBuildInputContributors, createBuildInputsFingerprint, didBuildInputContributorChange, hashAppConfigFile, haveBuildInputsChanged, } from '../build/cache/build-input-fingerprint.js';
 /** Builds the static-render invalidation context for one app config. */
 export declare function createRouteModuleStaticRenderCacheContext(appConfig: EcoPagesAppConfig): RouteModuleStaticRenderCacheContext;
 /** Returns whether `dist/` should be wiped before the next static export. */

package/src/static-site-generator/static-build-invalidation.js

@@ -2,8 +2,8 @@ import {
   createBuildInputsFingerprint,
   hashAppConfigFile,
   haveBuildInputsChanged
-} from "../build/build-input-fingerprint.js";
-import { clearPersistedProductionBuildCacheManifests } from "../build/production-build-cache.js";
+} from "../build/cache/build-input-fingerprint.js";
+import { clearPersistedProductionBuildCacheManifests } from "../build/cache/production-build-cache.js";
 import {} from "../services/module-loading/route-module-build-manifest.js";
 import {
   getSharedRouteModuleBuildCache,
@@ -15,7 +15,7 @@ import {
   didBuildInputContributorChange,
   hashAppConfigFile as hashAppConfigFile2,
   haveBuildInputsChanged as haveBuildInputsChanged2
-} from "../build/build-input-fingerprint.js";
+} from "../build/cache/build-input-fingerprint.js";
 function createRouteModuleStaticRenderCacheContext(appConfig) {
   return {
     configHash: hashAppConfigFile(appConfig),

package/src/static-site-generator/static-site-generator.js

@@ -8,7 +8,15 @@ import {
   getServerModuleBuildCacheOutdir,
   getSharedRouteModuleBuildCache
 } from "../services/module-loading/route-module-build-cache-registry.js";
-import { ensurePagesUnifiedGraphBuilt, shouldBuildPagesUnifiedGraph } from "../build/pages-unified-graph-build.js";
+import {
+  ensurePagesUnifiedGraphBuilt,
+  shouldBuildPagesUnifiedGraph
+} from "../build/cache/pages-unified-graph-build.js";
+import {
+  clearProductionPageBrowserGraphSession,
+  prebuildProductionPageBrowserGraphs,
+  shouldPrebuildProductionPageBrowserGraphs
+} from "./production-page-browser-graph-prebuild.js";
 const STATIC_SITE_GENERATOR_ERRORS = {
   ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy",
   unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
@@ -241,6 +249,9 @@ class StaticSiteGenerator {
     if (!force) {
       this.getRouteModuleBuildCache().ensureIncrementalStaticGenerationContext(this.staticRenderCacheContext);
     }
+    if (shouldPrebuildProductionPageBrowserGraphs() && force) {
+      clearProductionPageBrowserGraphSession(this.appConfig);
+    }
     const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
     if (shouldBuildPagesUnifiedGraph()) {
       await ensurePagesUnifiedGraphBuilt({
@@ -260,6 +271,12 @@ class StaticSiteGenerator {
     });
     await this.invokeStaticExportHook("beforeStaticExport", staticExportContext);
     try {
+      if (shouldPrebuildProductionPageBrowserGraphs() && routeRendererFactory) {
+        await prebuildProductionPageBrowserGraphs(
+          routes.map((route) => route.templateRoute.filePath),
+          routeRendererFactory
+        );
+      }
       this.generateRobotsTxt();
       await this.generateStaticPages(
         router,
@@ -280,6 +297,11 @@ class StaticSiteGenerator {
       if (preserveExportDirectory) {
         this.pruneStaleStaticOutputs(activeStaticPathnames);
       }
+    } catch (error) {
+      if (shouldPrebuildProductionPageBrowserGraphs()) {
+        clearProductionPageBrowserGraphSession(this.appConfig);
+      }
+      throw error;
     } finally {
       await this.invokeStaticExportHook("afterStaticExport", staticExportContext);
     }

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

@@ -1,7 +1,7 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { AppBuildManifest } from '../build/build-manifest.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
+import type { AppBuildManifest } from '../build/contracts/build-manifest.js';
 import type { BuildAdapter, BuildOwnership } from '../build/build-adapter.js';
-import type { BuildRuntime } from '../build/build-runtime.js';
+import type { BuildRuntime } from '../build/runtime/build-runtime.js';
 import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';
 import type { EcoSourceTransform } from '../plugins/source-transform.js';
@@ -12,6 +12,7 @@ import type { DevGraphService } from '../services/runtime-state/dev-graph.servic
 import type { AppModuleLoader } from '../services/module-loading/app-module-loader.service.js';
 import type { SourceModuleLoader } from '../services/module-loading/module-loading-types.js';
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { SessionPageBrowserGraphCache } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
 import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.js';
 import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
 import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
@@ -155,6 +156,7 @@ export type EcoPagesAppConfig = {
         buildManifest?: AppBuildManifest;
         devGraphService?: DevGraphService;
         entrypointDependencyGraph?: EntrypointDependencyGraph;
+        pageBrowserGraphSession?: SessionPageBrowserGraphCache;
         hostModuleLoader?: SourceModuleLoader;
         rendererModuleContext?: unknown;
         serverInvalidationState?: ServerInvalidationState;
@@ -164,6 +166,10 @@ export type EcoPagesAppConfig = {
         buildRuntime?: BuildRuntime;
         /** Set after {@link setupAppRuntimePlugins} runs processor/integration setup once per process. */
         runtimeAssetsPrepared?: boolean;
+        /** Registers integration runtime plugins when lazy activation completes. */
+        onRuntimePlugin?: (plugin: import('../build/contracts/build-types.js').EcoBuildPlugin) => void;
+        /** Integration names that completed lazy runtime activation. */
+        activatedIntegrations?: Set<string>;
         /** When `'host'`, the embedded dev server owns browser dev-client bootstrap. */
         devClientOwner?: 'core' | 'host';
         /** Integration hooks run when a registered `dependencies.scripts` entrypoint changes. */
@@ -236,4 +242,4 @@ export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown
         server: unknown;
     }>;
 }
-export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.js';
+export type { ClientBridgeEvent, DefaultHmrContext, HmrFileChangeOptions, IHmrManager, IClientBridge, } from './public-types.js';

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

@@ -1,7 +1,7 @@
 import type { Readable } from 'node:stream';
 import type { ApiResponseBuilder } from '../adapters/shared/api-response.js';
 import type { BuildExecutor } from '../build/build-adapter.js';
-import type { ForeignChildRuntime } from '../route-renderer/orchestration/component-render-context.js';
+import type { ForeignChildRuntime } from '../route-renderer/orchestration/foreign-child/component-render-context.js';
 import type { EcoPageComponent } from '../eco/eco.types.js';
 import type { EcoPagesAppConfig } from './internal-types.js';
 import type { HmrStrategy } from '../hmr/hmr-strategy.js';
@@ -204,6 +204,14 @@ export interface DefaultHmrContext {
      * Entrypoint dependency graph for selective HMR invalidation.
      */
     getEntrypointDependencyGraph(): EntrypointDependencyGraph;
+    /**
+     * Registers an already-materialized HMR entrypoint without rebuilding it.
+     *
+     * @remarks
+     * Cold dev batches seed the registrar after grouped builds so the first SSR
+     * resolves the artifact from disk instead of triggering a rebuild.
+     */
+    seedResolvedEntrypoint(resolved: ResolvedHmrEntrypoint): void;
 }
 /**
  * Represents an event broadcast to connected clients via the ClientBridge.
@@ -225,6 +233,22 @@ export type ClientBridgeEvent = {
      * Timestamp for cache busting
      */
     timestamp?: number;
+    /**
+     * Page Browser Graph identities invalidated by the originating file change.
+     */
+    graphIdentities?: Array<{
+        integrationName: string;
+        routeFile: string;
+        policy: 'development' | 'production';
+        entryFingerprint: string;
+    }>;
+};
+/**
+ * Options for handling a development file change through HMR.
+ */
+export type HmrFileChangeOptions = {
+    broadcast?: boolean;
+    graphIdentities?: ClientBridgeEvent['graphIdentities'];
 };
 /**
  * Adapter-agnostic interface for broadcasting development events to connected clients.
@@ -296,6 +320,14 @@ export interface IHmrManager {
      * Returns an existing emitted HMR script artifact without registering it.
      */
     getResolvedScriptOutput?(entrypointPath: string): ResolvedHmrEntrypoint | undefined;
+    /**
+     * Registers an already-materialized HMR entrypoint without rebuilding it.
+     *
+     * @remarks
+     * Cold dev batches seed the registrar after grouped builds so the first SSR
+     * resolves the artifact from disk instead of triggering a rebuild.
+     */
+    seedResolvedEntrypoint?(resolved: ResolvedHmrEntrypoint): void;
     /**
      * Gets the map of watched files.
      */
@@ -311,7 +343,7 @@ export interface IHmrManager {
     /**
      * Handles a file change event.
      */
-    handleFileChange(path: string): Promise<void>;
+    handleFileChange(path: string, options?: HmrFileChangeOptions): Promise<void>;
 }
 /**
  * Represents the dependencies for an EcoComponent.
@@ -345,17 +377,16 @@ export type EcoPagesElement = string | Promise<string>;
 /**
  * Serializable child payloads accepted by cross-integration deferred rendering.
  *
- * This models the broad value shapes that EcoPages already flattens when a
- * foreign component boundary serializes its children for another integration.
- * It is intentionally transport-oriented rather than framework-native, so it
- * can be shared across Kita, Lit, React, and Ecopages JSX authoring surfaces
- * without coupling core types to any one renderer.
+ * @remarks
+ * Covers primitives, arrays, and Kita/Lit-style template results (`strings` /
+ * optional `values`). Plain opaque objects are intentionally excluded; foreign
+ * composition boundaries reject them before serializers can coerce `String(object)`.
+ * Framework-native trees (React nodes, JSX elements) stay outside this type and
+ * use EcoEmbed or already-serialized HTML at the boundary.
  */
 export type EcoChildren = string | Promise<string> | number | bigint | boolean | null | undefined | readonly EcoChildren[] | {
     strings: readonly string[];
     values?: readonly EcoChildren[];
-} | {
-    [key: string]: EcoChildren;
 };
 /**
  * Represents the input configuration for EcoPages.
@@ -535,6 +566,15 @@ export interface HtmlTemplateProps<T = EcoPagesElement> extends PageHeadProps<T>
     language?: string;
     headContent?: T;
     pageProps: Record<string, unknown>;
+    /**
+     * Browser-importable page module URL for router-enabled documents.
+     *
+     * @remarks
+     * Transport-only: threaded into HTML shells (for example `EcoPropsScript`
+     * `moduleUrl`) and serialized as the page-data envelope `moduleUrl`. Not page
+     * component state.
+     */
+    pageModuleUrl?: string;
 }
 /**
  * Request-scoped context available to layout prop factories on `eco.page`.
@@ -789,7 +829,6 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     dependencies?: EcoComponentDependencies;
     resolvedDependencies: ProcessedAsset[];
     pagePackage?: PagePackageResult;
-    componentRender?: ComponentRenderResult;
     pageProps?: Record<string, unknown>;
     cacheStrategy?: CacheStrategy;
     pageLocals?: RequestLocals;
@@ -894,6 +933,16 @@ export interface BaseIntegrationContext {
     rendererCache?: Map<string, unknown>;
     componentInstanceId?: string;
 }
+/**
+ * Shared input for renderer-owned component execution.
+ *
+ * @remarks
+ * `children` stays `unknown` at this boundary so integrations can receive
+ * queued tokens, already-serialized HTML, or framework-native values before
+ * their own placement rules apply. Opaque values must be rejected or converted
+ * by foreign-child interception before string serializers run; adapters keep
+ * framework-specific placement (React raw HTML, Lit slot markers).
+ */
 export interface ComponentRenderInput<TIntegrationContext extends BaseIntegrationContext = BaseIntegrationContext> {
     component: EcoComponent;
     props: Record<string, unknown>;

package/src/watchers/project-watcher.d.ts

@@ -116,9 +116,9 @@ export declare class ProjectWatcher {
      */
     private matchesAdditionalWatchPaths;
     /**
-     * Checks if a file is handled by a processor.
-     * Processors that declare asset capabilities own those file types.
-     * Processors without capabilities fall back to checking watch extensions.
+     * Checks if a file is owned by a processor as an asset input.
+     * Ownership requires declared asset capabilities; watch config only drives
+     * {@link notifyProcessors} notifications.
      */
     private isHandledByProcessor;
     /**