@ecopages/core 0.2.0-beta.25 → 0.2.0-beta.27

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-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-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

@@ -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.js

@@ -5,6 +5,8 @@ import { appLogger } from "../global/app-logger.js";
 import {
   DevelopmentInvalidationService
 } from "../services/invalidation/development-invalidation.service.js";
+import { prepareHmrFileChange } from "../hmr/hmr-file-change-prep.js";
+import { getAppPageBrowserGraphSession } from "../route-renderer/orchestration/page-browser-graph-session.js";
 import { isRegisteredScriptEntrypoint } from "../hmr/hmr-entrypoint-output.js";
 import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
 import { createProjectWatcherIgnorePredicate } from "./project-watcher-ignore.js";
@@ -150,6 +152,10 @@ class ProjectWatcher {
       }
       this.uncacheModules();
       const resolvedFilePath = path.resolve(filePath);
+      const graphPreparation = this.hmrManager.isEnabled() ? prepareHmrFileChange(this.appConfig, resolvedFilePath) : void 0;
+      if (plan.refreshRoutes && (event === "unlink" || event === "add")) {
+        getAppPageBrowserGraphSession(this.appConfig).invalidateByRouteFile(resolvedFilePath);
+      }
       const isRegisteredScriptEdit = isRegisteredScriptEntrypoint(
         this.hmrManager.getWatchedFiles(),
         resolvedFilePath
@@ -167,7 +173,9 @@ class ProjectWatcher {
       const deferProcessorNotifications = plan.category === "include-source" || plan.category === "explicit-server-view" || isRegisteredScriptEdit;
       if (deferProcessorNotifications && plan.delegateToHmr) {
         await this.prewarmBeforeHmr(resolvedFilePath, plan);
-        await this.hmrManager.handleFileChange(filePath);
+        await this.hmrManager.handleFileChange(filePath, {
+          graphIdentities: graphPreparation?.affectedGraphIdentities
+        });
         await this.notifyProcessors(filePath, event);
         return;
       }
@@ -176,7 +184,9 @@ class ProjectWatcher {
         return;
       }
       if (plan.delegateToHmr) {
-        await this.hmrManager.handleFileChange(filePath);
+        await this.hmrManager.handleFileChange(filePath, {
+          graphIdentities: graphPreparation?.affectedGraphIdentities
+        });
       }
     } catch (error) {
       if (error instanceof Error) {

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

@@ -1,33 +0,0 @@
-import type { EcoBuildPlugin } from './build-types.js';
-import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
-export interface AppBuildManifest {
-    loaderPlugins: EcoBuildPlugin[];
-    runtimePlugins: EcoBuildPlugin[];
-    browserBundlePlugins: EcoBuildPlugin[];
-    browserRuntimeManifest: BrowserRuntimeManifest;
-}
-/**
- * Merges plugin lists while preserving first-registration precedence by name.
- *
- * @remarks
- * Build manifests treat plugin names as stable identities. The first plugin
- * with a given name wins so config-time assembly stays deterministic across
- * loader, runtime, and browser buckets.
- */
-export declare function mergeEcoBuildPlugins(...pluginLists: Array<EcoBuildPlugin[] | undefined>): EcoBuildPlugin[];
-/**
- * Creates one app-owned build manifest from the supplied plugin buckets.
- */
-export declare function createAppBuildManifest(input?: Partial<AppBuildManifest>): AppBuildManifest;
-/**
- * Returns the shared browser runtime asset manifest sealed into the app build manifest.
- */
-export declare function getBrowserRuntimeManifest(manifest: AppBuildManifest): BrowserRuntimeManifest;
-/**
- * Returns the plugin list used for server-oriented builds.
- */
-export declare function getServerBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[];
-/**
- * Returns the plugin list used for browser-oriented builds.
- */
-export declare function getBrowserBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[];

package/src/build/deduping-build-executor.js

@@ -1,56 +0,0 @@
-import path from "node:path";
-import { createJsxCacheKey, createPluginCacheKey } from "../services/module-loading/route-module-build-manifest.js";
-function createBuildOptionsDedupeKey(options) {
-  return [
-    normalizeEntrypoints(options.entrypoints),
-    options.root ? path.resolve(options.root) : "root:default",
-    options.outdir ? path.resolve(options.outdir) : "outdir:default",
-    options.splitting ?? "splitting:default",
-    options.externalPackages ?? "externalPackages:default",
-    options.target ?? "target:default",
-    options.format ?? "format:default",
-    options.sourcemap ?? "sourcemap:default",
-    options.minify ?? "minify:default",
-    options.treeshaking ?? "treeshaking:default",
-    options.naming ?? "naming:default",
-    createJsxCacheKey(options.jsx),
-    createPluginCacheKey(options.plugins)
-  ].join("::");
-}
-function normalizeEntrypoints(entrypoints) {
-  if (Array.isArray(entrypoints)) {
-    return entrypoints.map((entrypoint) => path.resolve(entrypoint)).sort().join("|");
-  }
-  return Object.entries(entrypoints).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}:${path.resolve(value)}`).join("|");
-}
-class DedupingBuildExecutor {
-  inner;
-  inFlight = /* @__PURE__ */ new Map();
-  constructor(inner) {
-    this.inner = inner;
-  }
-  build(options) {
-    const key = createBuildOptionsDedupeKey(options);
-    const existing = this.inFlight.get(key);
-    if (existing) {
-      return existing;
-    }
-    const buildPromise = this.inner.build(options).finally(() => {
-      if (this.inFlight.get(key) === buildPromise) {
-        this.inFlight.delete(key);
-      }
-    });
-    this.inFlight.set(key, buildPromise);
-    return buildPromise;
-  }
-  unwrap() {
-    return this.inner;
-  }
-  getInFlightCountForTests() {
-    return this.inFlight.size;
-  }
-}
-export {
-  DedupingBuildExecutor,
-  createBuildOptionsDedupeKey
-};

package/src/build/runtime-build-executor.d.ts

@@ -1,14 +0,0 @@
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import type { BuildExecutor } from './build-adapter.js';
-export type { BuildProfile, BuildRuntime } from './build-runtime.js';
-export { disposeAppBuildRuntime, getBuildRuntime, installBuildRuntime, requireBuildRuntime } from './build-runtime.js';
-/**
- * Installs the app-owned runtime build executors for one app instance.
- *
- * @remarks
- * Delegates to {@link installBuildRuntime}. Route-module and HMR browser builds
- * use parallel one-shot Rolldown. Server-entry bundling stays serialized
- * single-flight.
- */
-export declare function installAppRuntimeBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
-export declare function getInstalledServerEntryBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;

package/src/build/runtime-build-executor.js

@@ -1,16 +0,0 @@
-import { installBuildRuntime, requireBuildRuntime } from "./build-runtime.js";
-import { disposeAppBuildRuntime, getBuildRuntime, installBuildRuntime as installBuildRuntime2, requireBuildRuntime as requireBuildRuntime2 } from "./build-runtime.js";
-function installAppRuntimeBuildExecutor(appConfig) {
-  return installBuildRuntime(appConfig).getProfile("route-module");
-}
-function getInstalledServerEntryBuildExecutor(appConfig) {
-  return requireBuildRuntime(appConfig).getProfile("server-entry");
-}
-export {
-  disposeAppBuildRuntime,
-  getBuildRuntime,
-  getInstalledServerEntryBuildExecutor,
-  installAppRuntimeBuildExecutor,
-  installBuildRuntime2 as installBuildRuntime,
-  requireBuildRuntime2 as requireBuildRuntime
-};