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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.36",
+  "version": "0.2.0-beta.38",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.36",
+    "@ecopages/file-system": "0.2.0-beta.38",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.141.0",
@@ -32,7 +32,7 @@
     "@standard-schema/utils": "^0.3.0"
   },
   "peerDependencies": {
-    "@ecopages/dev-toolbar": "0.2.0-beta.36"
+    "@ecopages/dev-toolbar": "0.2.0-beta.38"
   },
   "peerDependenciesMeta": {
     "@ecopages/dev-toolbar": {
@@ -80,6 +80,10 @@
       "types": "./src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.d.ts",
       "default": "./src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.js"
     },
+    "./route-renderer/page-loading/file-scoped-dependency-components": {
+      "types": "./src/route-renderer/page-loading/file-scoped-dependency-components.d.ts",
+      "default": "./src/route-renderer/page-loading/file-scoped-dependency-components.js"
+    },
     "./route-renderer/orchestration/foreign-child/owning-renderer-resolution": {
       "types": "./src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.d.ts",
       "default": "./src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.js"
@@ -357,6 +361,10 @@
       "types": "./src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.d.ts",
       "default": "./src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.js"
     },
+    "./route-renderer/page-loading/file-scoped-dependency-components.ts": {
+      "types": "./src/route-renderer/page-loading/file-scoped-dependency-components.d.ts",
+      "default": "./src/route-renderer/page-loading/file-scoped-dependency-components.js"
+    },
     "./route-renderer/orchestration/foreign-child/owning-renderer-resolution.ts": {
       "types": "./src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.d.ts",
       "default": "./src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.js"

package/src/dev-toolbar/README.md

@@ -14,16 +14,16 @@ Server-side wiring for the development-only in-browser inspector. Public docs: [
 
 ## Module map
 
-| File                           | Role                                                                       |
-| ------------------------------ | -------------------------------------------------------------------------- |
-| `dev-toolbar-host.ts`          | Enablement, manifest contribution, runtime bundling, HTML injection        |
+| File                               | Role                                                                                                                                                                        |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dev-toolbar-host.ts`              | Enablement, manifest contribution, runtime bundling, HTML injection                                                                                                         |
 | `dev-toolbar-manifest-contract.ts` | `#__ECO_DEV_MANIFEST__` id and payload types (public: `@ecopages/core/dev-toolbar/dev-toolbar-manifest-contract`; mirrored in `@ecopages/dev-toolbar` for browser bundling) |
-| `dev-toolbar-manifest.ts`      | Builds and serializes the per-page dev manifest                            |
-| `dev-toolbar-package.ts`       | Resolves `devToolbar.package` bootstrap entry (`bootstrap.js`, then `.ts`) |
-| `dev-toolbar-config.ts`        | `isDevToolbarEnabled` — watch mode, env var, package required              |
-| `dev-toolbar-html-response.ts` | Adapter helpers for injecting `import '/_dev_toolbar.js'`                  |
-| `dev-toolbar-runtime-paths.ts` | `/_dev_toolbar.js` URL and work-dir paths                                  |
-| `define-dev-tool.ts`           | Config helper for bring-your-own client packages                           |
+| `dev-toolbar-manifest.ts`          | Builds and serializes the per-page dev manifest                                                                                                                             |
+| `dev-toolbar-package.ts`           | Resolves `devToolbar.package` bootstrap entry (`bootstrap.js`, then `.ts`)                                                                                                  |
+| `dev-toolbar-config.ts`            | `isDevToolbarEnabled` — watch mode, env var, package required                                                                                                               |
+| `dev-toolbar-html-response.ts`     | Adapter helpers for injecting `import '/_dev_toolbar.js'`                                                                                                                   |
+| `dev-toolbar-runtime-paths.ts`     | `/_dev_toolbar.js` URL and work-dir paths                                                                                                                                   |
+| `define-dev-tool.ts`               | Config helper for bring-your-own client packages                                                                                                                            |
 
 ## Injection order
 

package/src/eco/eco.browser.js

@@ -22,12 +22,16 @@ function layout(options) {
     return createComponentFactory(options);
 }
 function page(options) {
-    const { layout: pageLayout, dependencies, render, staticPaths, staticProps, metadata, cache, requires, middleware, } = options;
+    const { layout: pageLayout, dependencies: dependenciesInput, render, staticPaths, staticProps, metadata, cache, requires, middleware, } = options;
     const layoutEntries = normalizePageLayouts(pageLayout);
+    const resolveDependencies = typeof dependenciesInput === 'function' ? dependenciesInput : undefined;
+    const staticDependencies = typeof dependenciesInput === 'function'
+        ? mergeLayoutDependencies(undefined, layoutEntries)
+        : mergeLayoutDependencies(dependenciesInput, layoutEntries);
     const pageComponent = createComponentFactory({
         __eco: options.__eco,
         integration: options.integration,
-        dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
+        dependencies: staticDependencies,
         render,
     });
     if (pageComponent.config) {
@@ -42,6 +46,9 @@ function page(options) {
     if (metadata) {
         pageComponent.metadata = metadata;
     }
+    if (resolveDependencies) {
+        pageComponent.resolveDependencies = resolveDependencies;
+    }
     if (cache) {
         pageComponent.cache = cache;
     }

package/src/eco/eco.js

@@ -110,12 +110,16 @@ function layout(options) {
  * @returns Eco page component.
  */
 function page(options) {
-    const { layout, dependencies, render, staticPaths, staticProps, metadata, cache, requires, middleware } = options;
+    const { layout, dependencies: dependenciesInput, render, staticPaths, staticProps, metadata, cache, requires, middleware, } = options;
     const layoutEntries = normalizePageLayouts(layout);
+    const resolveDependencies = typeof dependenciesInput === 'function' ? dependenciesInput : undefined;
+    const staticDependencies = typeof dependenciesInput === 'function'
+        ? mergeLayoutDependencies(undefined, layoutEntries)
+        : mergeLayoutDependencies(dependenciesInput, layoutEntries);
     const componentOptions = {
         __eco: options.__eco,
         integration: options.integration,
-        dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
+        dependencies: staticDependencies,
         render,
     };
     const pageComponent = createComponentFactory(componentOptions);
@@ -128,6 +132,8 @@ function page(options) {
         pageComponent.staticProps = staticProps;
     if (metadata)
         pageComponent.metadata = metadata;
+    if (resolveDependencies)
+        pageComponent.resolveDependencies = resolveDependencies;
     if (cache)
         pageComponent.cache = cache;
     if (requires)

package/src/eco/eco.types.d.ts

@@ -2,7 +2,7 @@
  * Type definitions for the eco namespace API
  * @module
  */
-import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayouts, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
+import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayouts, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext, PageParams, PageQuery } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
 /**
  * Extracts the props type from one eco component.
@@ -54,6 +54,28 @@ type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K>
 };
 type RequiresKeys = keyof RequestLocals;
 export type PageRequires<K extends RequiresKeys = RequiresKeys> = K | readonly K[];
+/**
+ * Context passed to a page `dependencies` resolver for one concrete route render.
+ */
+export type GetPageDependenciesContext<T = Record<string, unknown>> = {
+    props: PagePropsFor<T>;
+    params?: PageParams;
+    query?: PageQuery;
+};
+/**
+ * Page dependency bag optionally scoped to a declaring file.
+ */
+export type PageDependenciesResult = EcoComponentDependencies & {
+    ownerFile?: string;
+};
+/**
+ * Resolves request-specific page dependencies for one route render.
+ */
+export type GetPageDependencies<T = Record<string, unknown>> = (context: GetPageDependenciesContext<T>) => PageDependenciesResult | undefined | Promise<PageDependenciesResult | undefined>;
+/**
+ * Static page dependencies or a per-render resolver.
+ */
+export type PageDependenciesInput<T = Record<string, unknown>> = EcoComponentDependencies | GetPageDependencies<T>;
 /**
  * Lazy trigger options map directly to scripts-injector attributes.
  * Only one trigger type can be active at a time.
@@ -91,7 +113,11 @@ export interface PageOptionsBase<T, E = EcoPagesElement> {
     /** @internal Injected by eco-component-meta-plugin */
     __eco?: EcoInjectedMeta;
     integration?: string;
-    dependencies?: EcoComponentDependencies;
+    /**
+     * Declares browser dependencies for the page, or resolves them per render after
+     * `staticProps` are available.
+     */
+    dependencies?: PageDependenciesInput<T>;
     layout?: EcoPageLayouts<E>;
     /**
      * Define static paths for dynamic routes (e.g., [slug].tsx).
@@ -178,6 +204,7 @@ export type EcoPageComponent<T> = EcoComponent<PagePropsFor<T> & Partial<Request
     staticPaths?: GetStaticPaths;
     staticProps?: GetStaticProps<T>;
     metadata?: GetMetadata<T>;
+    resolveDependencies?: GetPageDependencies<T>;
     cache?: CacheStrategy;
     requires?: PageRequires;
     middleware?: FileRouteMiddleware[];

package/src/hmr/README.md

@@ -37,11 +37,11 @@ Hosts call `prepareHmrFileChange()` before HMR dispatch (`hmr/hmr-file-change-pr
 
 ## Client events
 
-| Event | Client behavior |
-| --- | --- |
-| `update` | Cache-bust and re-import the changed module URL (or reload the active page module) |
-| `css-update` | Refresh matching stylesheet `link` hrefs |
+| Event           | Client behavior                                                                                                                                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `update`        | Cache-bust and re-import the changed module URL (or reload the active page module)                                                                                                                         |
+| `css-update`    | Refresh matching stylesheet `link` hrefs                                                                                                                                                                   |
 | `layout-update` | Soft current-page reload with layout cache cleared (`persistLayouts` remounts the updated layout without a full document reload). Falls back to `location.reload()` only if no navigation owner handles it |
-| `reload` | Full `location.reload()` |
+| `reload`        | Full `location.reload()`                                                                                                                                                                                   |
 
 Dev-transform local imports are rewritten with a content-hash query (`?v=…`) so transitive layout/component modules get a new ESM module-map key after invalidation. Soft `layout-update` then picks up the new layout while shared outer layout persistence still applies across normal SPA navigations.

package/src/route-renderer/README.md

@@ -84,7 +84,7 @@ The route-render contract is:
 
 1. `RouteRendererFactory` selects the owning integration renderer.
 2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderOrchestrator`.
-3. `RouteRenderOrchestrator.prepareRenderOptions()` loads the page module, validates ownership (fail-fast), resolves page data, resolves dependencies, and builds the page browser graph.
+3. `RouteRenderOrchestrator.prepareRenderOptions()` loads the page module, validates ownership (fail-fast), resolves final page props, resolves dependencies, and builds the page browser graph. Graph cache identity includes route params and query; contribution collection receives those same final props.
 4. The integration renderer performs page, layout, and document-shell rendering. When it encounters a foreign child, it delegates that child back to the owning renderer.
 5. If a renderer needs queued handoff, it emits internal foreign-subtree tokens and resolves them before returning final HTML.
 6. `RouteRenderOrchestrator.executePrepared()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps document attributes when needed, and runs the HTML transformer.
@@ -93,6 +93,7 @@ Important:
 
 - route-level fallback resolution is gone; unresolved artifacts are now a hard failure
 - ownership is declared from component metadata, not inferred from final HTML
+- declared page dependencies are resolved from final render inputs and carried to the owning integration; integrations may use them for renderer-specific lifecycle work such as HMR ownership
 - same-integration children stay renderer-local and do not need to pass through a universal transport
 
 ## Declared Foreign Child Contract

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,6 +12,8 @@ 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';
 /**
@@ -72,9 +74,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 +130,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.
      *
@@ -270,6 +283,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),
         });
     }
     /**
@@ -494,6 +530,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 +544,21 @@ export class IntegrationRenderer {
         });
     }
     async resolveRouteRenderInputs(routeOptions) {
-        const pageModule = await this.pageModuleLoaderService.resolvePageModule({
+        const resolvedPageModule = await this.pageModuleLoaderService.resolvePageModule({
             file: routeOptions.file,
             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 +568,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/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,23 @@ 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;
     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 +97,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.