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

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

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { getAppPageBrowserGraphSession } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
+import { createPageDependencyInstanceKey } from '../route-renderer/orchestration/page-browser-graph/route-instance-key.js';
 /**
  * Returns whether production static export should warm Page Browser Graphs before rendering.
  *
@@ -20,19 +21,37 @@ export function shouldPrebuildProductionPageBrowserGraphs() {
 export function clearProductionPageBrowserGraphSession(appConfig) {
     getAppPageBrowserGraphSession(appConfig).clearPolicyRecords('production');
 }
+function serializeProductionRouteInstance(instance) {
+    const routeFile = path.resolve(instance.routeFile);
+    const dependencyInstanceKey = createPageDependencyInstanceKey({ params: instance.params });
+    return JSON.stringify([routeFile, dependencyInstanceKey]);
+}
 /**
- * Warms production Page Browser Graphs for the supplied static route files.
+ * Warms production Page Browser Graphs for the supplied static route instances.
  *
  * @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.
+ * Deduplicates route file + params pairs, 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 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 async function prebuildProductionPageBrowserGraphs(routeInstances, routeRendererFactory) {
+    const uniqueRouteInstances = [
+        ...new Map(routeInstances.map((instance) => [serializeProductionRouteInstance(instance), instance])).values(),
+    ].sort((left, right) => serializeProductionRouteInstance(left).localeCompare(serializeProductionRouteInstance(right)));
+    const instancesByRenderer = new Map();
+    for (const routeInstance of uniqueRouteInstances) {
+        const renderer = routeRendererFactory.getPageRenderer(routeInstance.routeFile);
+        const instances = instancesByRenderer.get(renderer) ?? [];
+        instances.push(routeInstance);
+        instancesByRenderer.set(renderer, instances);
+    }
+    for (const [renderer, routeInstancesForRenderer] of instancesByRenderer) {
+        const groupedBuildPlan = await renderer.buildGroupedGraphBuildPlan(routeInstancesForRenderer);
+        for (const routeInstance of routeInstancesForRenderer) {
+            await renderer.prebuildProductionPageBrowserGraph(routeInstance.routeFile, {
+                params: routeInstance.params,
+                groupedBuildPlan,
+            });
+        }
     }
 }

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

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

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

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

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

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

package/src/watchers/project-watcher.js

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

package/src/route-renderer/orchestration/page-browser-graph/page-browser-graph-contribution.loader.d.ts

@@ -1,9 +0,0 @@
-import type { EcoPageFile, PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../../../types/public-types.js';
-/**
- * Loads a page module once and collects declarative browser-graph requirements.
- *
- * @remarks
- * Shared by route orchestration prep and the integration route-render adapter so
- * page imports are not duplicated when both paths need the same contribution.
- */
-export declare function loadPageBrowserGraphContribution(routeFile: string, importPageFile: (file: string) => Promise<EcoPageFile>, collectContribution: (context: PageBrowserGraphContributionContext) => Promise<PageBrowserGraphContribution | undefined>): Promise<PageBrowserGraphContribution | undefined>;

package/src/route-renderer/orchestration/page-browser-graph/page-browser-graph-contribution.loader.js

@@ -1,11 +0,0 @@
-/**
- * Loads a page module once and collects declarative browser-graph requirements.
- *
- * @remarks
- * Shared by route orchestration prep and the integration route-render adapter so
- * page imports are not duplicated when both paths need the same contribution.
- */
-export async function loadPageBrowserGraphContribution(routeFile, importPageFile, collectContribution) {
-    const pageModule = await importPageFile(routeFile);
-    return collectContribution({ file: routeFile, pageModule });
-}