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

package/src/route-renderer/orchestration/integration-renderer.d.ts

@@ -4,7 +4,7 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, EcoPagesElement, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 import { HtmlTransformerService } from '../../services/html/html-transformer.service.js';
 import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
@@ -12,18 +12,15 @@ import { HttpError } from '../../errors/http-error.js';
 import { DependencyResolverService } from '../page-loading/dependency-resolver.js';
 import { PageModuleLoaderService } from '../page-loading/page-module-loader.js';
 import { RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-pipeline/route-render-orchestrator.js';
+import { type ResolvedPageDependencies } from '../page-loading/resolved-page-dependencies.js';
+import { type GroupedGraphBuildPlan } from './page-browser-graph/grouped-graph-build-plan.js';
 import type { ForeignChildRuntime } from './foreign-child/component-render-context.js';
 import { ForeignSubtreeExecutionService } from './foreign-child/foreign-subtree-execution.service.js';
 /**
  * Controls how one route module is loaded outside the normal render path.
- *
- * Request-time metadata inspection and static-generation probes use these
- * options to isolate their module identity from the main render cache while
- * still going through the owning integration's import setup.
  */
 export type RouteModuleLoadOptions = {
     bypassCache?: boolean;
-    cacheScope?: string;
 };
 /**
  * Context for renderToResponse method.
@@ -72,9 +69,19 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected ensureIntegrationRuntimeActivated(): Promise<void>;
     /**
-     * Prebuilds the production Page Browser Graph for one route file.
+     * Prebuilds the production Page Browser Graph for one route file and optional params.
      */
-    prebuildProductionPageBrowserGraph(routeFile: string): Promise<void>;
+    prebuildProductionPageBrowserGraph(routeFile: string, options?: Pick<RouteRendererOptions, 'params' | 'query'> & {
+        groupedBuildPlan?: GroupedGraphBuildPlan;
+    }): Promise<void>;
+    /**
+     * Builds one production grouped graph plan for the supplied static route instances.
+     */
+    buildGroupedGraphBuildPlan(instances: ReadonlyArray<{
+        routeFile: string;
+        params?: RouteRendererOptions['params'];
+        query?: RouteRendererOptions['query'];
+    }>): Promise<GroupedGraphBuildPlan>;
     /**
      * Loads one route module through the owning renderer's import path.
      *
@@ -118,6 +125,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
     protected resolvePageBrowserGraphForFile(filePath: string): Promise<PageBrowserGraphResult | undefined>;
+    protected resolvePageBrowserGraphForRoute(filePath: string, routeOptions?: Pick<RouteRendererOptions, 'params' | 'query'>, groupedBuildPlan?: GroupedGraphBuildPlan): Promise<PageBrowserGraphResult | undefined>;
     /**
      * Merges component-scoped assets into the active HTML transformer state.
      *
@@ -226,12 +234,9 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns The HTML template component.
      */
     protected getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
-    protected usesIntegrationPageImporter(_file: string): boolean;
-    protected importIntegrationPageFile(_file: string, _options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
     protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(_file: string, pageModule: TPageModule): TPageModule;
     /**
      * Imports the page file from the specified path.
-     * It uses dynamic import to load the file and returns the imported module.
      *
      * @param file - The file path to import.
      * @returns The imported module.
@@ -270,6 +275,9 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected createRouteRenderOrchestratorAdapter(): RouteRenderOrchestratorAdapter<C>;
     protected resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
+    protected buildPageBrowserGraphContributionContext(routeFile: string, routeOptions?: Pick<RouteRendererOptions, 'params' | 'query'>): Promise<PageBrowserGraphContributionContext>;
+    protected resolvePageDependencies(context: PageBrowserGraphContributionContext): Promise<ResolvedPageDependencies | undefined>;
+    protected resolvePageBrowserGraphContributionFromDependencies(dependencies: EcoComponentDependencies, ownerFile: string): Promise<PageBrowserGraphContribution | undefined>;
     protected resolveRouteDependencies(input: {
         components: (EcoComponent | Partial<EcoComponent>)[];
     }): Promise<{

package/src/route-renderer/orchestration/integration-renderer.js

@@ -13,7 +13,11 @@ import { OwnershipValidationService } from './ownership-graph/ownership-validati
 import { hasForeignChildDescendantsInGraph } from './ownership-graph/component-graph-collectors.js';
 import { RouteRenderOrchestrator, } from './route-pipeline/route-render-orchestrator.js';
 import { createIntegrationRouteRenderAdapter } from './route-pipeline/integration-route-render-adapter.js';
-import { loadPageBrowserGraphContribution } from './page-browser-graph/page-browser-graph-contribution.loader.js';
+import { createPageDependencyInstanceKey } from './page-browser-graph/route-instance-key.js';
+import { mergePageBrowserGraphContributions } from './page-browser-graph/page-browser-graph-contribution.merge.js';
+import { collectDependencyWatchPaths, collectFileScopedDependencyComponents, } from '../page-loading/file-scoped-dependency-components.js';
+import { resolvePageDependenciesFromContext, } from '../page-loading/resolved-page-dependencies.js';
+import { createGroupedGraphBuildPlanKey, } from './page-browser-graph/grouped-graph-build-plan.js';
 import { normalizeUnresolvedMarkerArtifactHtml } from './route-pipeline/marker-artifact.utils.js';
 import { isMarkupNodeLike } from './foreign-child/foreign-child-output.utils.js';
 import { getForeignSubtreeResolutionContextKey, getForeignSubtreeTokenPrefix, resolveOwningIntegrationRenderer, } from './foreign-child/owning-renderer-resolution.js';
@@ -66,11 +70,30 @@ export class IntegrationRenderer {
         });
     }
     /**
-     * Prebuilds the production Page Browser Graph for one route file.
+     * Prebuilds the production Page Browser Graph for one route file and optional params.
      */
-    async prebuildProductionPageBrowserGraph(routeFile) {
+    async prebuildProductionPageBrowserGraph(routeFile, options) {
         await this.ensureIntegrationRuntimeActivated();
-        await this.resolvePageBrowserGraphForFile(routeFile);
+        await this.resolvePageBrowserGraphForRoute(routeFile, options, options?.groupedBuildPlan);
+    }
+    /**
+     * Builds one production grouped graph plan for the supplied static route instances.
+     */
+    async buildGroupedGraphBuildPlan(instances) {
+        const builtInstances = await Promise.all(instances.map(async (routeInstance) => {
+            const context = await this.buildPageBrowserGraphContributionContext(routeInstance.routeFile, routeInstance);
+            const resolvedPageDependencies = await this.resolvePageDependencies(context);
+            return {
+                routeFile: routeInstance.routeFile,
+                dependencyInstanceKey: context.dependencyInstanceKey ?? '',
+                contribution: mergePageBrowserGraphContributions(await this.collectPageBrowserGraphContribution(context), resolvedPageDependencies?.contribution),
+            };
+        }));
+        return {
+            integrationName: this.name,
+            planKey: createGroupedGraphBuildPlanKey(this.name, builtInstances),
+            instances: builtInstances,
+        };
     }
     /**
      * Loads one route module through the owning renderer's import path.
@@ -173,10 +196,23 @@ export class IntegrationRenderer {
         return resolvedDependencies;
     }
     async resolvePageBrowserGraphForFile(filePath) {
+        /**
+         * @remarks
+         * Integration renderers such as React still call this file-only entry point
+         * during explicit view rendering. Route-instance-aware callers should prefer
+         * `resolvePageBrowserGraphForRoute`.
+         */
+        return this.resolvePageBrowserGraphForRoute(filePath);
+    }
+    async resolvePageBrowserGraphForRoute(filePath, routeOptions, groupedBuildPlan) {
+        const graphContext = await this.buildPageBrowserGraphContributionContext(filePath, routeOptions);
+        const resolvedPageDependencies = await this.resolvePageDependencies(graphContext);
         return await this.routeRenderOrchestrator.resolveDeclaredPageBrowserGraph({
             routeFile: filePath,
+            dependencyInstanceKey: graphContext.dependencyInstanceKey,
             integrationName: this.name,
-            collectContribution: (routeFile) => loadPageBrowserGraphContribution(routeFile, (targetFile) => this.importPageFile(targetFile), (context) => this.collectPageBrowserGraphContribution(context)),
+            groupedBuildPlan,
+            collectContribution: async () => mergePageBrowserGraphContributions(await this.collectPageBrowserGraphContribution(graphContext), resolvedPageDependencies?.contribution),
         });
     }
     /**
@@ -330,14 +366,14 @@ export class IntegrationRenderer {
                     ? input.children.outerHTML
                     : undefined;
         if (input.children !== undefined && serializedChildren === undefined) {
-            const componentFile = input.component.config?.__eco?.file ?? 'unknown component';
+            const componentFile = input.component.config?.identity?.file ?? 'unknown component';
             const childTag = Object.prototype.toString.call(input.children);
             throw new TypeError(`[ecopages] ${this.name} renderer expected serialized children for ${componentFile}, received ${childTag}.`);
         }
         const props = serializedChildren === undefined ? input.props : { ...input.props, children: serializedChildren };
         const content = await component(props);
         if (typeof content !== 'string') {
-            const componentFile = input.component.config?.__eco?.file ?? 'unknown component';
+            const componentFile = input.component.config?.identity?.file ?? 'unknown component';
             const contentTag = Object.prototype.toString.call(content);
             throw new TypeError(`[ecopages] ${this.name} renderer expected a string render result for ${componentFile}, received ${contentTag}.`);
         }
@@ -417,33 +453,19 @@ export class IntegrationRenderer {
             invariant(false, `Error importing HtmlTemplate: ${error}`);
         }
     }
-    usesIntegrationPageImporter(_file) {
-        return false;
-    }
-    async importIntegrationPageFile(_file, _options) {
-        invariant(false, 'Integration page importer must be implemented when enabled');
-    }
     normalizeImportedPageFile(_file, pageModule) {
         return pageModule;
     }
     /**
      * Imports the page file from the specified path.
-     * It uses dynamic import to load the file and returns the imported module.
      *
      * @param file - The file path to import.
      * @returns The imported module.
      */
     async importPageFile(file, options) {
-        const bypassCache = options?.bypassCache ?? false;
-        const pageModule = this.usesIntegrationPageImporter(file)
-            ? await this.importIntegrationPageFile(file, {
-                bypassCache,
-                cacheScope: options?.cacheScope,
-            })
-            : await this.pageModuleLoaderService.importPageFile(file, {
-                bypassCache,
-                cacheScope: options?.cacheScope,
-            });
+        const pageModule = await this.pageModuleLoaderService.importPageFile(file, {
+            bypassCache: options?.bypassCache,
+        });
         return this.normalizeImportedPageFile(file, pageModule);
     }
     /**
@@ -494,6 +516,8 @@ export class IntegrationRenderer {
             resolveRouteDependencies: (input) => this.resolveRouteDependencies(input),
             importPageFile: (file) => this.importPageFile(file),
             collectPageBrowserGraphContribution: (context) => this.collectPageBrowserGraphContribution(context),
+            resolvePageDependencies: (context) => this.resolvePageDependencies(context),
+            buildPageBrowserGraphContributionContext: (routeFile, routeOptions) => this.buildPageBrowserGraphContributionContext(routeFile, routeOptions),
             renderRouteBody: (renderOptions) => this.renderRouteBody(renderOptions),
             getDocumentAttributes: (renderOptions) => this.getDocumentAttributes(renderOptions),
             getHtmlDocumentContributions: (options) => this.getHtmlDocumentContributions(options),
@@ -506,20 +530,22 @@ export class IntegrationRenderer {
         });
     }
     async resolveRouteRenderInputs(routeOptions) {
-        const pageModule = await this.pageModuleLoaderService.resolvePageModule({
+        const resolvedPageModule = await this.pageModuleLoaderService.resolvePageModule({
             file: routeOptions.file,
+            pageModule: routeOptions.pageModule,
             importPageFileFn: (targetFile) => this.importPageFile(targetFile),
         });
-        const { Page, integrationSpecificProps } = pageModule;
+        const { Page, integrationSpecificProps, module: pageModule } = resolvedPageModule;
         const HtmlTemplate = await this.getHtmlTemplate();
         const Layouts = resolvePageLayoutComponents(Page.config?.layouts);
         const Layout = resolveInnermostPageLayout(Layouts);
         const { props, metadata } = await this.pageModuleLoaderService.resolvePageData({
-            pageModule,
+            pageModule: resolvedPageModule,
             routeOptions,
         });
         return {
             Page,
+            pageModule,
             HtmlTemplate: HtmlTemplate,
             Layouts,
             Layout,
@@ -529,6 +555,48 @@ export class IntegrationRenderer {
             integrationSpecificProps,
         };
     }
+    async buildPageBrowserGraphContributionContext(routeFile, routeOptions) {
+        const { module: pageModule, ...resolvedPageModule } = await this.pageModuleLoaderService.resolvePageModule({
+            file: routeFile,
+            importPageFileFn: (targetFile) => this.importPageFile(targetFile),
+        });
+        const { props } = await this.pageModuleLoaderService.resolvePageData({
+            pageModule: resolvedPageModule,
+            routeOptions: {
+                file: routeFile,
+                params: routeOptions?.params,
+                query: routeOptions?.query,
+            },
+        });
+        return {
+            file: routeFile,
+            pageModule,
+            props,
+            params: routeOptions?.params,
+            query: routeOptions?.query,
+            dependencyInstanceKey: createPageDependencyInstanceKey({
+                params: routeOptions?.params,
+                query: routeOptions?.query,
+            }),
+        };
+    }
+    async resolvePageDependencies(context) {
+        return resolvePageDependenciesFromContext(context, this.name, (dependencies, ownerFile) => this.resolvePageBrowserGraphContributionFromDependencies(dependencies, ownerFile));
+    }
+    async resolvePageBrowserGraphContributionFromDependencies(dependencies, ownerFile) {
+        const components = collectFileScopedDependencyComponents({
+            ownerFile,
+            integrationName: this.name,
+            dependencies,
+        });
+        if (components.length === 0) {
+            return undefined;
+        }
+        return {
+            assets: await this.processComponentDependencies(components),
+            watchPaths: collectDependencyWatchPaths(ownerFile, components),
+        };
+    }
     async resolveRouteDependencies(input) {
         return {
             resolvedDependencies: await this.resolveDependencies(input.components),

package/src/route-renderer/orchestration/ownership-graph/component-graph-collectors.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { AssetFactory } from '../../../services/assets/asset-processing-service/index.js';
 import { walkComponentGraph } from './component-graph.js';
+import { getComponentIdentity } from '../../../eco/component-identity.js';
 function toGraphRoots(components) {
     return components.filter(Boolean).map((component) => ({ component }));
 }
@@ -10,7 +11,7 @@ export function collectIntegrationNamesFromGraph(components, currentIntegrationN
         roots: toGraphRoots(components),
         currentIntegrationName,
         onComponent: ({ component }) => {
-            const integrationName = component.config?.integration ?? component.config?.__eco?.integration;
+            const integrationName = getComponentIdentity(component)?.integration ?? component.config?.integration;
             if (integrationName) {
                 integrationNames.add(integrationName);
             }
@@ -41,7 +42,7 @@ export function hasForeignChildDescendantsInGraph(component, currentIntegrationN
             if (foundForeign) {
                 return false;
             }
-            const integrationName = currentComponent.config?.integration ?? currentComponent.config?.__eco?.integration;
+            const integrationName = getComponentIdentity(currentComponent)?.integration ?? currentComponent.config?.integration;
             if (integrationName && integrationName !== currentIntegrationName) {
                 foundForeign = true;
                 return false;
@@ -63,8 +64,8 @@ export function collectEagerSsrLazyScriptDefinitions(components) {
         currentIntegrationName: '',
         visitLayout: true,
         onConfig: (config) => {
-            const componentFile = config?.__eco?.file;
-            if (!componentFile) {
+            const componentFile = getComponentIdentity(config)?.file;
+            if (!componentFile || !config) {
                 return;
             }
             const componentDir = path.dirname(componentFile);

package/src/route-renderer/orchestration/ownership-graph/component-graph.js

@@ -1,3 +1,4 @@
+import { getComponentIdentity } from '../../../eco/component-identity.js';
 export function walkComponentGraph(input) {
     const seenComponents = new Set();
     const seenConfigs = new Set();
@@ -10,7 +11,8 @@ export function walkComponentGraph(input) {
             return;
         }
         seenComponents.add(ecoComponent);
-        const integrationName = ecoComponent.config?.integration ?? ecoComponent.config?.__eco?.integration ?? parentIntegrationName;
+        const identity = getComponentIdentity(ecoComponent);
+        const integrationName = ecoComponent.config?.integration ?? identity?.integration ?? parentIntegrationName;
         if (input.onConfig && ecoComponent.config && !seenConfigs.has(ecoComponent.config)) {
             seenConfigs.add(ecoComponent.config);
             input.onConfig(ecoComponent.config);
@@ -62,10 +64,10 @@ export function walkComponentGraph(input) {
 export function mapComponentGraph(input) {
     let nextSyntheticId = 0;
     const mapComponent = (component, source, parentIntegrationName, lineage) => {
-        const integrationName = component.config?.integration ?? component.config?.__eco?.integration ?? parentIntegrationName;
-        const componentMeta = component.config?.__eco;
+        const identity = getComponentIdentity(component);
+        const integrationName = component.config?.integration ?? identity?.integration ?? parentIntegrationName;
         const isForeignToParent = integrationName !== parentIntegrationName;
-        const componentId = componentMeta?.id ?? componentMeta?.file ?? `${source}:${(nextSyntheticId += 1)}`;
+        const componentId = identity?.id ?? identity?.file ?? `${source}:${(nextSyntheticId += 1)}`;
         const nextLineage = new Set(lineage);
         nextLineage.add(component);
         const children = (component.config?.dependencies?.components ?? []).flatMap((child) => {

package/src/route-renderer/orchestration/ownership-graph/ownership-validation.service.d.ts

@@ -24,7 +24,6 @@ export declare class OwnershipValidationService {
      * Validates foreign ownership edges reachable from the supplied route roots.
      */
     validate(input: OwnershipValidationInput): OwnershipValidationError[];
-    private assertDeclaredComponentDependencies;
     private isRegisteredIntegration;
 }
 /**

package/src/route-renderer/orchestration/ownership-graph/ownership-validation.service.js

@@ -1,5 +1,6 @@
 import { assertEcoDeclaredComponent } from '../../../eco/eco-declared-component.js';
-import { mapComponentGraph, walkComponentGraph } from './component-graph.js';
+import { getComponentIdentity } from '../../../eco/component-identity.js';
+import { mapComponentGraph } from './component-graph.js';
 /**
  * Validates foreign ownership as soon as the route root graph is loaded.
  *
@@ -19,12 +20,17 @@ export class OwnershipValidationService {
      * Validates foreign ownership edges reachable from the supplied route roots.
      */
     validate(input) {
-        this.assertDeclaredComponentDependencies(input);
         return mapComponentGraph({
             roots: input.roots,
             currentIntegrationName: input.currentIntegrationName,
             mapNode: ({ component, integrationName, componentId, isForeignToParent }, children) => {
-                const componentMeta = component.config?.__eco;
+                const parentFile = getComponentIdentity(component)?.file;
+                for (const child of component.config?.dependencies?.components ?? []) {
+                    if (child) {
+                        assertEcoDeclaredComponent(child, { parentComponentFile: parentFile });
+                    }
+                }
+                const componentMeta = getComponentIdentity(component);
                 const errors = children.flat();
                 if (!isForeignToParent) {
                     return errors;
@@ -35,7 +41,7 @@ export class OwnershipValidationService {
                 if (!componentMeta) {
                     errors.push({
                         code: 'MISSING_COMPONENT_METADATA',
-                        message: `[ecopages] Foreign child "${componentId}" must provide stable __eco metadata so ownership diagnostics stay actionable. Declared dependencies must include all possible foreign children.`,
+                        message: `[ecopages] Foreign child "${componentId}" must provide stable component identity so ownership diagnostics stay actionable. Declared dependencies must include all possible foreign children.`,
                         componentId,
                         integrationName,
                     });
@@ -53,21 +59,6 @@ export class OwnershipValidationService {
             },
         }).flat();
     }
-    assertDeclaredComponentDependencies(input) {
-        walkComponentGraph({
-            roots: input.roots,
-            currentIntegrationName: input.currentIntegrationName,
-            onComponent: ({ component }) => {
-                const parentFile = component.config?.__eco?.file;
-                for (const child of component.config?.dependencies?.components ?? []) {
-                    if (!child) {
-                        continue;
-                    }
-                    assertEcoDeclaredComponent(child, { parentComponentFile: parentFile });
-                }
-            },
-        });
-    }
     isRegisteredIntegration(integrationName, currentIntegrationName) {
         if (integrationName === currentIntegrationName) {
             return true;

package/src/route-renderer/orchestration/page-browser-graph/grouped-graph-build-plan.d.ts

@@ -0,0 +1,15 @@
+import type { PageBrowserGraphContribution } from '../../../types/public-types.js';
+export type GroupedGraphBuildPlanInstance = {
+    routeFile: string;
+    dependencyInstanceKey: string;
+    contribution?: PageBrowserGraphContribution;
+};
+export type GroupedGraphBuildPlan = {
+    integrationName: string;
+    planKey: string;
+    instances: ReadonlyArray<GroupedGraphBuildPlanInstance>;
+};
+/**
+ * Builds a stable grouped-cache identity for one integration static export plan.
+ */
+export declare function createGroupedGraphBuildPlanKey(integrationName: string, instances: ReadonlyArray<Pick<GroupedGraphBuildPlanInstance, 'routeFile' | 'dependencyInstanceKey'>>): string;

package/src/route-renderer/orchestration/page-browser-graph/grouped-graph-build-plan.js

@@ -0,0 +1,9 @@
+/**
+ * Builds a stable grouped-cache identity for one integration static export plan.
+ */
+export function createGroupedGraphBuildPlanKey(integrationName, instances) {
+    const canonicalInstances = [...instances]
+        .map((instance) => [instance.routeFile, instance.dependencyInstanceKey])
+        .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    return JSON.stringify(['grouped-plan', integrationName, canonicalInstances]);
+}

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

@@ -0,0 +1,5 @@
+import type { PageBrowserGraphContribution } from '../../../types/public-types.js';
+/**
+ * Merges multiple Page Browser Graph contributions into one declarative payload.
+ */
+export declare function mergePageBrowserGraphContributions(...contributions: Array<PageBrowserGraphContribution | undefined>): PageBrowserGraphContribution | undefined;

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

@@ -0,0 +1,30 @@
+/**
+ * Merges multiple Page Browser Graph contributions into one declarative payload.
+ */
+export function mergePageBrowserGraphContributions(...contributions) {
+    const dependencies = [];
+    const assets = [];
+    const watchPaths = new Set();
+    for (const contribution of contributions) {
+        if (!contribution) {
+            continue;
+        }
+        if (contribution.dependencies?.length) {
+            dependencies.push(...contribution.dependencies);
+        }
+        if (contribution.assets?.length) {
+            assets.push(...contribution.assets);
+        }
+        for (const watchPath of contribution.watchPaths ?? []) {
+            watchPaths.add(watchPath);
+        }
+    }
+    if (dependencies.length === 0 && assets.length === 0 && watchPaths.size === 0) {
+        return undefined;
+    }
+    return {
+        ...(dependencies.length > 0 ? { dependencies } : {}),
+        ...(assets.length > 0 ? { assets } : {}),
+        ...(watchPaths.size > 0 ? { watchPaths: Array.from(watchPaths) } : {}),
+    };
+}

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

@@ -1,3 +1,4 @@
+import type { GroupedGraphScope } from './route-instance-key.js';
 import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
 import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../../types/public-types.js';
 import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/assets.types.js';
@@ -5,6 +6,7 @@ export type GraphPolicy = 'development' | 'production';
 export type GraphKey = {
     integrationName: string;
     routeFile: string;
+    dependencyInstanceKey: string;
     entryFingerprint: string;
     policy: GraphPolicy;
 };
@@ -18,6 +20,11 @@ export type GraphRecord = {
 export type GraphBuildResult = {
     result: PageBrowserGraphResult;
     dependencyPaths: ReadonlySet<string>;
+    /**
+     * @remarks
+     * When false, the build result is returned to callers but not committed to the session cache.
+     */
+    cacheable?: boolean;
 };
 type GroupedGraphRecord = {
     assetsByRoute: Map<string, ProcessedAsset[]>;
@@ -32,6 +39,7 @@ export type GroupedGraphBuildOutcome = GroupedGraphRecord | {
 export type AffectedGraphIdentity = {
     integrationName: string;
     routeFile: string;
+    dependencyInstanceKey: string;
     policy: GraphPolicy;
     entryFingerprint: string;
 };
@@ -42,8 +50,10 @@ export declare class GraphDependencyIndex {
     private readonly dependencyToGraphKeys;
     bindRecord(record: GraphRecord): void;
     unbindRecord(record: GraphRecord): void;
-    bindGroupedRecord(integrationName: string, record: GroupedGraphRecord): void;
-    unbindGroupedRecord(integrationName: string, record: GroupedGraphRecord): void;
+    bindGroupedRecord(cacheKey: string, record: GroupedGraphRecord): void;
+    unbindGroupedRecord(cacheKey: string, record: GroupedGraphRecord): void;
+    bindPaths(serializedKey: string, dependencyPaths: ReadonlySet<string>): void;
+    unbindPaths(serializedKey: string, dependencyPaths: ReadonlySet<string>): void;
     getAffectedKeys(filePath: string): Set<string>;
     resetForTests(): void;
     private addDependencyBinding;
@@ -55,21 +65,24 @@ export declare class GraphDependencyIndex {
 export declare class SessionPageBrowserGraphCache {
     private readonly records;
     private readonly inFlight;
+    private readonly inFlightDependencyPaths;
+    private readonly inFlightGenerations;
     private readonly groupedRecords;
     private readonly groupedInFlight;
     private readonly dependencyIndex;
     private readonly graphGenerations;
     private readonly groupedGenerations;
     private buildCount;
-    getGraphByRoute(integrationName: string, routeFile: string, policy: GraphPolicy): PageBrowserGraphResult | undefined;
     /**
      * Page Browser Graph compilations in this dev-server session.
      */
     getBuildCount(): number;
+    getGraphByRoute(integrationName: string, routeFile: string, policy: GraphPolicy, dependencyInstanceKey?: string): PageBrowserGraphResult | undefined;
+    getDependencyPathsByRoute(integrationName: string, routeFile: string, policy: GraphPolicy, dependencyInstanceKey?: string): ReadonlySet<string> | undefined;
     getAffectedGraphIdentities(filePath: string): AffectedGraphIdentity[];
-    resolveGraph(key: GraphKey, build: () => Promise<GraphBuildResult | undefined>): Promise<PageBrowserGraphResult | undefined>;
-    resolveGroupedGraph(integrationName: string, build: () => Promise<GroupedGraphBuildOutcome | undefined>): Promise<Map<string, ProcessedAsset[]>>;
-    peekGroupedGraph(integrationName: string): Map<string, ProcessedAsset[]> | undefined;
+    resolveGraph(key: GraphKey, provisionalDependencyPaths: ReadonlySet<string>, build: () => Promise<GraphBuildResult | undefined>): Promise<PageBrowserGraphResult | undefined>;
+    resolveGroupedGraph(scope: GroupedGraphScope, build: () => Promise<GroupedGraphBuildOutcome | undefined>): Promise<Map<string, ProcessedAsset[]>>;
+    peekGroupedGraph(scope: GroupedGraphScope): Map<string, ProcessedAsset[]> | undefined;
     invalidateByFilePath(filePath: string): number;
     invalidateRoute(integrationName: string, routeFile: string): void;
     invalidateByRouteFile(routeFile: string): void;
@@ -85,6 +98,10 @@ export declare class SessionPageBrowserGraphCache {
     private runGroupedBuild;
     private canCommitGraphBuild;
     private canCommitGroupedBuild;
+    private bindDependencyPaths;
+    private unbindDependencyPaths;
+    private clearInFlightBuild;
+    private releaseInFlightDependencyPaths;
 }
 /**
  * Returns the session graph cache for one app instance.