@ecopages/core 0.2.0-beta.36 → 0.2.0-beta.38

package/src/route-renderer/orchestration/page-browser-graph/route-instance-key.js

@@ -0,0 +1,54 @@
+/**
+ * Builds a stable cache key for one concrete dependency resolver input.
+ *
+ * @remarks
+ * The representation deliberately retains scalar versus array values. Delimiter-based
+ * encodings would make otherwise distinct route inputs collide.
+ */
+export function createPageDependencyInstanceKey(input) {
+    const params = canonicalizeInput(input.params);
+    const query = canonicalizeInput(input.query);
+    if (params.length === 0 && query.length === 0) {
+        return '';
+    }
+    return JSON.stringify({ params, query });
+}
+/**
+ * Combines a route file with an optional dependency-instance key for grouped graph maps.
+ */
+export function createRouteGraphLookupKey(routeFile, dependencyInstanceKey = '') {
+    return JSON.stringify([routeFile, dependencyInstanceKey]);
+}
+/**
+ * Serializes the grouped graph cache scope for one integration and dependency instance.
+ */
+export function serializeGroupedGraphCacheKey(scope) {
+    return JSON.stringify(['grouped', scope.integrationName, scope.planKey]);
+}
+/**
+ * Reconstructs dependency resolver inputs from a serialized dependency-instance key.
+ */
+export function parsePageDependencyInstanceKey(dependencyInstanceKey) {
+    if (!dependencyInstanceKey) {
+        return {};
+    }
+    const parsed = JSON.parse(dependencyInstanceKey);
+    if (!isSerializedDependencyInstance(parsed)) {
+        throw new TypeError('Invalid page dependency instance key.');
+    }
+    return {
+        ...(parsed.params.length > 0 ? { params: Object.fromEntries(parsed.params) } : {}),
+        ...(parsed.query.length > 0 ? { query: Object.fromEntries(parsed.query) } : {}),
+    };
+}
+function canonicalizeInput(input) {
+    return Object.entries(input ?? {})
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => [key, Array.isArray(value) ? [...value] : value]);
+}
+function isSerializedDependencyInstance(value) {
+    if (!value || typeof value !== 'object' || !('params' in value) || !('query' in value)) {
+        return false;
+    }
+    return Array.isArray(value.params) && Array.isArray(value.query);
+}

package/src/route-renderer/orchestration/route-pipeline/integration-route-render-adapter.d.ts

@@ -2,6 +2,7 @@ import type { ProcessedAsset } from '../../../services/assets/asset-processing-s
 import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
 import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
 import type { EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PagePackageResult, RouteRendererBody, RouteRendererOptions } from '../../../types/public-types.js';
+import type { ResolvedPageDependencies } from '../../page-loading/resolved-page-dependencies.js';
 import type { RouteHtmlFinalization, RouteRenderOrchestratorAdapter, RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
 /**
  * Host surface required to build the orchestrator adapter for one integration renderer.
@@ -19,6 +20,8 @@ export type IntegrationRouteRenderAdapterHost<C> = {
     }>;
     importPageFile(file: string): Promise<EcoPageFile>;
     collectPageBrowserGraphContribution(context: PageBrowserGraphContributionContext): Promise<PageBrowserGraphContribution | undefined>;
+    resolvePageDependencies(context: PageBrowserGraphContributionContext): Promise<ResolvedPageDependencies | undefined>;
+    buildPageBrowserGraphContributionContext(routeFile: string, routeOptions?: Pick<RouteRendererOptions, 'params' | 'query'>): Promise<PageBrowserGraphContributionContext>;
     renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
     getDocumentAttributes(renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
     getHtmlDocumentContributions(options: {

package/src/route-renderer/orchestration/route-pipeline/integration-route-render-adapter.js

@@ -1,4 +1,3 @@
-import { loadPageBrowserGraphContribution } from '../page-browser-graph/page-browser-graph-contribution.loader.js';
 import { buildRouteHtmlFinalization } from './route-html-finalization.service.js';
 /**
  * Builds the internal route-render adapter consumed by `RouteRenderOrchestrator`.
@@ -8,7 +7,9 @@ export function createIntegrationRouteRenderAdapter(host) {
         name: host.name,
         resolveRouteRenderInputs: (routeOptions) => host.resolveRouteRenderInputs(routeOptions),
         resolveRouteDependencies: (input) => host.resolveRouteDependencies(input),
-        collectPageBrowserGraphContribution: (routeFile) => loadPageBrowserGraphContribution(routeFile, (file) => host.importPageFile(file), (context) => host.collectPageBrowserGraphContribution(context)),
+        collectPageBrowserGraphContribution: (context) => host.collectPageBrowserGraphContribution(context),
+        resolvePageDependencies: (context) => host.resolvePageDependencies(context),
+        buildPageBrowserGraphContributionContext: (routeFile, routeOptions) => host.buildPageBrowserGraphContributionContext(routeFile, routeOptions),
         renderRouteBody: (renderOptions) => host.renderRouteBody(renderOptions),
         getRouteHtmlFinalization: (renderOptions) => buildRouteHtmlFinalization({
             appConfig: host.appConfig,

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

@@ -17,6 +17,7 @@ type PreparedRenderInputs = {
 export declare function buildPreparedRenderOptions<C = unknown>(input: {
     routeOptions: RouteRendererOptions;
     resolvedInputs: PreparedRenderInputs;
+    resolvedPageDependencyComponents?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
     resolvedDependencies: ProcessedAsset[];
     allDependencies: ProcessedAsset[];
     pageBrowserGraph?: PageBrowserGraphResult;

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

@@ -5,14 +5,11 @@ 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, resolvedDependencies, allDependencies, pageBrowserGraph, appConfig } = input;
+    const { routeOptions, resolvedInputs, resolvedPageDependencyComponents, resolvedDependencies, allDependencies, pageBrowserGraph, appConfig, } = input;
     const { Page, HtmlTemplate, Layouts, Layout, layoutEntries, props, metadata, integrationSpecificProps } = resolvedInputs;
     const dedupedDependencies = dedupeProcessedAssets(allDependencies);
     const pagePackage = createPagePackage(dedupedDependencies, { pageBrowserGraph });
-    const resolvedProps = {
-        ...props,
-        ...(routeOptions.props ?? {}),
-    };
+    const resolvedProps = props;
     const pageProps = {
         ...resolvedProps,
         params: routeOptions.params || {},
@@ -28,6 +25,7 @@ export function buildPreparedRenderOptions(input) {
     const locals = localsAvailable ? routeOptions.locals : undefined;
     const preparedOptions = {
         ...routeOptions,
+        resolvedPageDependencyComponents,
         resolvedDependencies,
         pagePackage,
         HtmlTemplate: HtmlTemplate,

package/src/route-renderer/orchestration/route-pipeline/route-render-orchestrator.d.ts

@@ -1,11 +1,14 @@
 import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
-import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult, EcoPageLayoutEntry } from '../../../types/public-types.js';
+import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult, EcoPageLayoutEntry } from '../../../types/public-types.js';
 import type { AssetProcessingService, ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
 import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
 import { OwnershipValidationService } from '../ownership-graph/ownership-validation.service.js';
 import { PageBrowserGraphService } from '../page-browser-graph/page-browser-graph.service.js';
+import type { GroupedGraphBuildPlan } from '../page-browser-graph/grouped-graph-build-plan.js';
+import type { ResolvedPageDependencies } from '../../page-loading/resolved-page-dependencies.js';
 export type RouteRenderOrchestratorResolvedInputs = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
+    pageModule: EcoPageFile;
     HtmlTemplate: EcoComponent<HtmlTemplateProps>;
     Layouts: EcoComponent[];
     Layout?: EcoComponent;
@@ -43,9 +46,14 @@ export interface RouteRenderOrchestratorAdapter<C> {
         components: (EcoComponent | Partial<EcoComponent>)[];
     }): Promise<RouteRenderOrchestratorResolvedDependencies>;
     /**
-     * Collects declarative Page Browser Graph requirements for one route.
+     * Collects declarative Page Browser Graph requirements for one route instance.
      */
-    collectPageBrowserGraphContribution(routeFile: string): Promise<PageBrowserGraphContribution | undefined>;
+    collectPageBrowserGraphContribution(context: PageBrowserGraphContributionContext): Promise<PageBrowserGraphContribution | undefined>;
+    resolvePageDependencies(context: PageBrowserGraphContributionContext): Promise<ResolvedPageDependencies | undefined>;
+    /**
+     * Builds the graph contribution context for one route file and optional params.
+     */
+    buildPageBrowserGraphContributionContext(routeFile: string, routeOptions?: Pick<RouteRendererOptions, 'params' | 'query'>): Promise<PageBrowserGraphContributionContext>;
     /**
      * Executes the Integration-specific route render.
      */
@@ -97,8 +105,10 @@ export declare class RouteRenderOrchestrator {
     prepareRenderOptions<C = unknown>(routeOptions: RouteRendererOptions, adapter: RouteRenderOrchestratorAdapter<C>): Promise<IntegrationRendererRenderOptions<C>>;
     resolveDeclaredPageBrowserGraph(input: {
         routeFile: string;
+        dependencyInstanceKey?: string;
         integrationName: string;
-        collectContribution: (routeFile: string) => Promise<PageBrowserGraphContribution | undefined>;
+        collectContribution: () => Promise<PageBrowserGraphContribution | undefined>;
+        groupedBuildPlan?: GroupedGraphBuildPlan;
     }): Promise<PageBrowserGraphResult | undefined>;
     /**
      * Captures one route render body as HTML while preserving a replayable body value.

package/src/route-renderer/orchestration/route-pipeline/route-render-orchestrator.js

@@ -2,7 +2,9 @@ import { inspectUnresolvedMarkerArtifactHtml } from './marker-artifact.utils.js'
 import { OwnershipValidationService, throwIfOwnershipInvalid, } from '../ownership-graph/ownership-validation.service.js';
 import { buildEagerSsrLazyAssetsFromGraph, collectResolvedLazyTriggersFromGraph, collectUsedIntegrationDependenciesFromGraph, } from '../ownership-graph/component-graph-collectors.js';
 import { buildGlobalInjectorAssets } from '../page-browser-graph/global-injector-assets.service.js';
+import { mergePageBrowserGraphContributions } from '../page-browser-graph/page-browser-graph-contribution.merge.js';
 import { PageBrowserGraphService } from '../page-browser-graph/page-browser-graph.service.js';
+import { createPageDependencyInstanceKey } from '../page-browser-graph/route-instance-key.js';
 import { buildPreparedRenderOptions } from './route-prepared-options.builder.js';
 /**
  * Owns one route render from normalized module loading through final HTML output.
@@ -34,7 +36,15 @@ export class RouteRenderOrchestrator {
      */
     async prepareRenderOptions(routeOptions, adapter) {
         const resolvedInputs = await adapter.resolveRouteRenderInputs(routeOptions);
-        const { Page, HtmlTemplate, Layouts } = resolvedInputs;
+        const finalProps = {
+            ...resolvedInputs.props,
+            ...(routeOptions.props ?? {}),
+        };
+        const finalResolvedInputs = {
+            ...resolvedInputs,
+            props: finalProps,
+        };
+        const { Page, HtmlTemplate, Layouts } = finalResolvedInputs;
         const validationErrors = this.ownershipValidationService.validate({
             currentIntegrationName: adapter.name,
             roots: [
@@ -45,16 +55,31 @@ export class RouteRenderOrchestrator {
         });
         throwIfOwnershipInvalid(validationErrors);
         const componentsToResolve = [HtmlTemplate, ...Layouts, Page];
+        const dependencyInstanceKey = createPageDependencyInstanceKey({
+            params: routeOptions.params,
+            query: routeOptions.query,
+        });
+        const graphContext = {
+            file: routeOptions.file,
+            pageModule: finalResolvedInputs.pageModule,
+            props: finalProps,
+            params: routeOptions.params,
+            query: routeOptions.query,
+            dependencyInstanceKey,
+        };
+        const resolvedPageDependencies = await adapter.resolvePageDependencies(graphContext);
         const [{ resolvedDependencies }, pageBrowserGraph] = await Promise.all([
             adapter.resolveRouteDependencies({
                 components: componentsToResolve,
             }),
             this.pageBrowserGraphService.resolvePageBrowserGraph({
                 routeFile: routeOptions.file,
+                dependencyInstanceKey,
                 integrationName: adapter.name,
-                collectContribution: async (routeFile) => await adapter.collectPageBrowserGraphContribution(routeFile),
+                collectContribution: async () => mergePageBrowserGraphContributions(await adapter.collectPageBrowserGraphContribution(graphContext), resolvedPageDependencies?.contribution),
             }),
         ]);
+        const resolvedPageDependencyComponents = resolvedPageDependencies?.components ?? [];
         const allDependencies = [
             ...resolvedDependencies,
             ...collectUsedIntegrationDependenciesFromGraph(this.appConfig, componentsToResolve, adapter.name),
@@ -69,7 +94,8 @@ export class RouteRenderOrchestrator {
         allDependencies.push(...globalAssets, ...eagerSsrLazyAssets);
         return buildPreparedRenderOptions({
             routeOptions,
-            resolvedInputs,
+            resolvedInputs: finalResolvedInputs,
+            resolvedPageDependencyComponents,
             resolvedDependencies,
             allDependencies,
             pageBrowserGraph,
@@ -110,7 +136,8 @@ export class RouteRenderOrchestrator {
         }
         const canReuseCapturedBody = !hasUnresolvedMarkerHtml && htmlFinalization.finalizeHtml === undefined;
         if (canReuseCapturedBody) {
-            const body = await adapter.transformRouteResponse(new Response(renderExecution.body, {
+            const responseBody = typeof renderExecution.body === 'string' ? renderExecution.body : renderExecution.html;
+            const body = await adapter.transformRouteResponse(new Response(responseBody, {
                 headers: {
                     'Content-Type': 'text/html',
                 },

package/src/route-renderer/page-loading/file-scoped-dependency-components.d.ts

@@ -0,0 +1,42 @@
+import type { EcoComponent, EcoComponentConfig, EcoComponentDependencies } from '../../types/public-types.js';
+import type { PageDependenciesResult } from '../../eco/eco.types.js';
+/**
+ * Attaches file-backed `__eco` metadata to one component config.
+ */
+export declare function attachEcoFileMetadataToConfig(config: EcoComponentConfig, ownerFile: string, integrationName: string): EcoComponentConfig;
+/**
+ * Builds a synthetic component config rooted at one file so direct dependency
+ * declarations can flow through the shared component dependency collector.
+ */
+export declare function createFileScopedDependencyComponent(options: {
+    ownerFile: string;
+    integrationName: string;
+    dependencies: Pick<EcoComponentDependencies, 'scripts' | 'stylesheets' | 'modules'>;
+}): Partial<EcoComponent> | undefined;
+/**
+ * Expands one dependency bag into component roots understood by the shared collector.
+ */
+export declare function collectFileScopedDependencyComponents(options: {
+    ownerFile: string;
+    integrationName: string;
+    dependencies: EcoComponentDependencies;
+}): Array<EcoComponent | Partial<EcoComponent>>;
+export type CollectComponentConfigFilePathsOptions = {
+    additionalPaths?: ReadonlyArray<string>;
+    includeLayouts?: boolean;
+};
+/**
+ * Walks component configs and collects every resolved `config.__eco.file` path.
+ */
+export declare function collectComponentConfigFilePaths(components: ReadonlyArray<EcoComponent | Partial<EcoComponent> | undefined>, options?: CollectComponentConfigFilePathsOptions): Set<string>;
+/**
+ * Collects source files that should invalidate a per-instance browser graph entry.
+ */
+export declare function collectDependencyWatchPaths(ownerFile: string, components: ReadonlyArray<EcoComponent | Partial<EcoComponent>>): string[];
+/**
+ * Separates optional owner metadata from a resolved page dependency bag.
+ */
+export declare function splitPageDependenciesResult(result: PageDependenciesResult): {
+    dependencies: EcoComponentDependencies;
+    ownerFile?: string;
+};

package/src/route-renderer/page-loading/file-scoped-dependency-components.js

@@ -0,0 +1,93 @@
+import path from 'node:path';
+import { rapidhash } from '../../utils/hash.js';
+/**
+ * Attaches file-backed `__eco` metadata to one component config.
+ */
+export function attachEcoFileMetadataToConfig(config, ownerFile, integrationName) {
+    return {
+        ...config,
+        __eco: {
+            id: config.__eco?.id ?? rapidhash(ownerFile).toString(36),
+            file: ownerFile,
+            integration: config.__eco?.integration ?? integrationName,
+        },
+    };
+}
+/**
+ * Builds a synthetic component config rooted at one file so direct dependency
+ * declarations can flow through the shared component dependency collector.
+ */
+export function createFileScopedDependencyComponent(options) {
+    const { scripts, stylesheets, modules } = options.dependencies;
+    if (!scripts?.length && !stylesheets?.length && !modules?.length) {
+        return undefined;
+    }
+    return {
+        config: attachEcoFileMetadataToConfig({ dependencies: { scripts, stylesheets, modules } }, options.ownerFile, options.integrationName),
+    };
+}
+/**
+ * Expands one dependency bag into component roots understood by the shared collector.
+ */
+export function collectFileScopedDependencyComponents(options) {
+    const components = [];
+    if (options.dependencies.components?.length) {
+        components.push(...options.dependencies.components);
+    }
+    const ownerComponent = createFileScopedDependencyComponent({
+        ownerFile: options.ownerFile,
+        integrationName: options.integrationName,
+        dependencies: options.dependencies,
+    });
+    if (ownerComponent) {
+        components.push(ownerComponent);
+    }
+    return components;
+}
+/**
+ * Walks component configs and collects every resolved `config.__eco.file` path.
+ */
+export function collectComponentConfigFilePaths(components, options) {
+    const files = new Set();
+    const visited = new Set();
+    for (const additionalPath of options?.additionalPaths ?? []) {
+        files.add(path.resolve(additionalPath));
+    }
+    const visit = (config) => {
+        const file = config?.__eco?.file;
+        if (!file) {
+            return;
+        }
+        const resolved = path.resolve(file);
+        if (visited.has(resolved)) {
+            return;
+        }
+        visited.add(resolved);
+        files.add(resolved);
+        for (const dependency of config.dependencies?.components ?? []) {
+            visit(dependency?.config);
+        }
+        if (options?.includeLayouts) {
+            for (const layout of config.layouts ?? []) {
+                visit(layout?.config);
+            }
+        }
+    };
+    for (const component of components) {
+        visit(component?.config);
+    }
+    return files;
+}
+/**
+ * Collects source files that should invalidate a per-instance browser graph entry.
+ */
+export function collectDependencyWatchPaths(ownerFile, components) {
+    return Array.from(collectComponentConfigFilePaths(components, { additionalPaths: [ownerFile] }));
+}
+/**
+ * Separates optional owner metadata from a resolved page dependency bag.
+ */
+export function splitPageDependenciesResult(result) {
+    const { ownerFile, ...dependencies } = result;
+    return { dependencies, ownerFile };
+}

package/src/route-renderer/page-loading/page-module-loader.d.ts

@@ -64,6 +64,7 @@ export declare class PageModuleLoaderService {
         file: string;
         importPageFileFn?: (file: string) => Promise<EcoPageFile>;
     }): Promise<{
+        module: EcoPageFile;
         Page: EcoPageFile['default'] | EcoPageComponent<any>;
         getStaticProps?: GetStaticProps<Record<string, unknown>>;
         getMetadata?: GetMetadata;

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

@@ -101,6 +101,7 @@ export class PageModuleLoaderService {
         const module = await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file);
         const { default: Page, getStaticProps: moduleGetStaticProps, getMetadata: moduleGetMetadata, ...integrationSpecificProps } = module;
         return {
+            module,
             Page,
             getStaticProps: Page.staticProps ?? moduleGetStaticProps,
             getMetadata: Page.metadata ?? moduleGetMetadata,

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

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

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

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

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

@@ -1,5 +1,10 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { PageParams } from '../types/public-types.js';
 import type { PageRendererResolver } from '../route-renderer/route-renderer.js';
+export type ProductionPageBrowserGraphRouteInstance = {
+    routeFile: string;
+    params?: PageParams;
+};
 /**
  * Returns whether production static export should warm Page Browser Graphs before rendering.
  *
@@ -17,12 +22,11 @@ export declare function shouldPrebuildProductionPageBrowserGraphs(): boolean;
  */
 export declare function clearProductionPageBrowserGraphSession(appConfig: EcoPagesAppConfig): void;
 /**
- * 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 declare function prebuildProductionPageBrowserGraphs(routeFiles: readonly string[], routeRendererFactory: PageRendererResolver): Promise<void>;
+export declare function prebuildProductionPageBrowserGraphs(routeInstances: readonly ProductionPageBrowserGraphRouteInstance[], routeRendererFactory: PageRendererResolver): Promise<void>;

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

@@ -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({

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

@@ -10,7 +10,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.
@@ -881,6 +881,8 @@ 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>;
@@ -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/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 });
-}