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

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

@@ -0,0 +1,29 @@
+import type { PageParams, PageQuery } from '../../../types/public-types.js';
+export type PageDependencyInstance = {
+    params?: PageParams;
+    query?: PageQuery;
+};
+export type GroupedGraphScope = {
+    integrationName: string;
+    planKey: string;
+};
+/**
+ * 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 declare function createPageDependencyInstanceKey(input: PageDependencyInstance): string;
+/**
+ * Combines a route file with an optional dependency-instance key for grouped graph maps.
+ */
+export declare function createRouteGraphLookupKey(routeFile: string, dependencyInstanceKey?: string): string;
+/**
+ * Serializes the grouped graph cache scope for one integration and dependency instance.
+ */
+export declare function serializeGroupedGraphCacheKey(scope: GroupedGraphScope): string;
+/**
+ * Reconstructs dependency resolver inputs from a serialized dependency-instance key.
+ */
+export declare function parsePageDependencyInstanceKey(dependencyInstanceKey: string): PageDependencyInstance;

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

@@ -1,9 +1,14 @@
+import { collectHtmlCacheSourceDependencyPaths } from '../../../services/cache/html-page-cache-dependency-index.js';
+import { getComponentIdentity } from '../../../eco/component-identity.js';
 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';
+import { measureRouteRenderPhase } from '../../../diagnostics/request-pipeline-metrics.js';
 /**
  * Owns one route render from normalized module loading through final HTML output.
  *
@@ -33,28 +38,56 @@ export class RouteRenderOrchestrator {
      * HTML transformation.
      */
     async prepareRenderOptions(routeOptions, adapter) {
-        const resolvedInputs = await adapter.resolveRouteRenderInputs(routeOptions);
-        const { Page, HtmlTemplate, Layouts } = resolvedInputs;
-        const validationErrors = this.ownershipValidationService.validate({
-            currentIntegrationName: adapter.name,
-            roots: [
-                { component: HtmlTemplate, source: 'html-template' },
-                ...Layouts.map((layout) => ({ component: layout, source: 'layout' })),
-                { component: Page, source: 'page' },
-            ],
+        const resolvedInputs = await measureRouteRenderPhase('resolve-route-inputs', () => adapter.resolveRouteRenderInputs(routeOptions));
+        const finalProps = {
+            ...resolvedInputs.props,
+            ...(routeOptions.props ?? {}),
+        };
+        const finalResolvedInputs = {
+            ...resolvedInputs,
+            props: finalProps,
+        };
+        const { Page, HtmlTemplate, Layouts } = finalResolvedInputs;
+        await measureRouteRenderPhase('ownership-validation', async () => {
+            const validationErrors = this.ownershipValidationService.validate({
+                currentIntegrationName: adapter.name,
+                roots: [
+                    { component: HtmlTemplate, source: 'html-template' },
+                    ...Layouts.map((layout) => ({ component: layout, source: 'layout' })),
+                    { component: Page, source: 'page' },
+                ],
+            });
+            throwIfOwnershipInvalid(validationErrors);
         });
-        throwIfOwnershipInvalid(validationErrors);
         const componentsToResolve = [HtmlTemplate, ...Layouts, Page];
-        const [{ resolvedDependencies }, pageBrowserGraph] = await Promise.all([
-            adapter.resolveRouteDependencies({
-                components: componentsToResolve,
-            }),
-            this.pageBrowserGraphService.resolvePageBrowserGraph({
-                routeFile: routeOptions.file,
-                integrationName: adapter.name,
-                collectContribution: async (routeFile) => await adapter.collectPageBrowserGraphContribution(routeFile),
-            }),
-        ]);
+        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 } = await measureRouteRenderPhase('resolve-dependencies', () => adapter.resolveRouteDependencies({
+            components: componentsToResolve,
+        }));
+        const pageBrowserGraph = await measureRouteRenderPhase('page-browser-graph', () => this.pageBrowserGraphService.resolvePageBrowserGraph({
+            routeFile: routeOptions.file,
+            dependencyInstanceKey,
+            integrationName: adapter.name,
+            collectContribution: async () => mergePageBrowserGraphContributions(await adapter.collectPageBrowserGraphContribution(graphContext), resolvedPageDependencies?.contribution),
+        }));
+        const graphDependencyPaths = this.pageBrowserGraphService.getDependencyPathsForRoute({
+            integrationName: adapter.name,
+            routeFile: routeOptions.file,
+            dependencyInstanceKey,
+        });
+        const resolvedPageDependencyComponents = resolvedPageDependencies?.components ?? [];
         const allDependencies = [
             ...resolvedDependencies,
             ...collectUsedIntegrationDependenciesFromGraph(this.appConfig, componentsToResolve, adapter.name),
@@ -67,14 +100,24 @@ export class RouteRenderOrchestrator {
             buildEagerSsrLazyAssetsFromGraph(this.assetProcessingService, componentsToResolve, adapter.name),
         ]);
         allDependencies.push(...globalAssets, ...eagerSsrLazyAssets);
-        return buildPreparedRenderOptions({
-            routeOptions,
-            resolvedInputs,
-            resolvedDependencies,
-            allDependencies,
-            pageBrowserGraph,
-            appConfig: this.appConfig,
+        const sourceDependencyPaths = collectHtmlCacheSourceDependencyPaths({
+            routeFile: routeOptions.file,
+            processedAssets: allDependencies,
+            graphDependencyPaths,
+            additionalSourcePaths: collectRenderShellSourcePaths(this.appConfig, componentsToResolve),
         });
+        return {
+            ...buildPreparedRenderOptions({
+                routeOptions,
+                resolvedInputs: finalResolvedInputs,
+                resolvedPageDependencyComponents,
+                resolvedDependencies,
+                allDependencies,
+                pageBrowserGraph,
+                appConfig: this.appConfig,
+            }),
+            sourceDependencyPaths,
+        };
     }
     async resolveDeclaredPageBrowserGraph(input) {
         return await this.pageBrowserGraphService.resolvePageBrowserGraph(input);
@@ -101,7 +144,7 @@ export class RouteRenderOrchestrator {
      * Executes the route-render finalization path for already prepared render options.
      */
     async executePrepared(renderOptions, adapter) {
-        const renderExecution = await this.captureHtmlRender(async () => adapter.renderRouteBody(renderOptions));
+        const renderExecution = await measureRouteRenderPhase('render-body', () => this.captureHtmlRender(async () => adapter.renderRouteBody(renderOptions)));
         const unresolvedArtifactInspection = inspectUnresolvedMarkerArtifactHtml(renderExecution.html);
         const htmlFinalization = adapter.getRouteHtmlFinalization(renderOptions);
         const hasUnresolvedMarkerHtml = unresolvedArtifactInspection.hasUnresolvedMarkerArtifacts;
@@ -110,27 +153,30 @@ 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 measureRouteRenderPhase('transform-response', () => adapter.transformRouteResponse(new Response(responseBody, {
                 headers: {
                     'Content-Type': 'text/html',
                 },
-            }), htmlFinalization.htmlContributions, renderOptions.pagePackage);
+            }), htmlFinalization.htmlContributions, renderOptions.pagePackage));
             return {
                 body,
                 cacheStrategy: renderOptions.cacheStrategy,
+                sourceDependencyPaths: renderOptions.sourceDependencyPaths,
             };
         }
         const finalization = htmlFinalization.finalizeHtml
             ? htmlFinalization.finalizeHtml(unresolvedArtifactInspection.normalizedHtml)
             : unresolvedArtifactInspection.normalizedHtml;
-        const body = await adapter.transformRouteResponse(new Response(finalization, {
+        const body = await measureRouteRenderPhase('transform-response', () => adapter.transformRouteResponse(new Response(finalization, {
             headers: {
                 'Content-Type': 'text/html',
             },
-        }), htmlFinalization.htmlContributions, renderOptions.pagePackage);
+        }), htmlFinalization.htmlContributions, renderOptions.pagePackage));
         return {
             body,
             cacheStrategy: renderOptions.cacheStrategy,
+            sourceDependencyPaths: renderOptions.sourceDependencyPaths,
         };
     }
     async captureRenderedBody(body) {
@@ -154,3 +200,16 @@ export class RouteRenderOrchestrator {
         };
     }
 }
+function collectRenderShellSourcePaths(appConfig, components) {
+    const sourcePaths = new Set();
+    if (appConfig.absolutePaths?.htmlTemplatePath) {
+        sourcePaths.add(appConfig.absolutePaths.htmlTemplatePath);
+    }
+    for (const component of components) {
+        const componentFile = getComponentIdentity(component)?.file;
+        if (componentFile) {
+            sourcePaths.add(componentFile);
+        }
+    }
+    return [...sourcePaths];
+}

package/src/route-renderer/page-loading/component-dependency-collection.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { assertEcoDeclaredComponent } from '../../eco/eco-declared-component.js';
+import { getComponentIdentity } from '../../eco/component-identity.js';
 import { AssetFactory } from '../../services/assets/asset-processing-service/index.js';
 import { extractEcopagesVirtualImports } from './ecopages-virtual-imports.js';
 import { collectDeclaredAssetEntries } from './declared-asset-collection.js';
@@ -43,7 +44,7 @@ export function collectComponentDependencies(options) {
     for (const component of components) {
         if (!component)
             continue;
-        const componentFile = component.config?.__eco?.file;
+        const componentFile = getComponentIdentity(component)?.file;
         if (!componentFile)
             continue;
         const stylesheetDependencyKeys = new Set();
@@ -55,7 +56,7 @@ export function collectComponentDependencies(options) {
         const collect = (config) => {
             if (!config)
                 return;
-            const file = config.__eco?.file;
+            const file = getComponentIdentity(config)?.file;
             if (!file)
                 return;
             const dir = path.dirname(file);

package/src/route-renderer/page-loading/ecopages-virtual-imports.d.ts

@@ -2,11 +2,6 @@ export type EcopagesVirtualImport = {
     from: string;
     imports: string[] | undefined;
 };
-/**
- * @remarks
- * Content server modules static-import every MDX entry. They must never become
- * browser module-script dependencies discovered from page or component sources.
- */
 export declare function isBrowserEcopagesVirtualImport(specifier: string): boolean;
 /**
  * Extracts runtime `ecopages:` virtual-module imports from a component source file.

package/src/route-renderer/page-loading/ecopages-virtual-imports.js

@@ -1,14 +1,8 @@
 import { readFileSync } from 'node:fs';
-import { parseSync } from 'oxc-parser';
-/** Matches `ecopages:content/<collection>/server` — SSR-only MDX resolver modules. */
-const CONTENT_SERVER_VIRTUAL_MODULE_PATTERN = /^ecopages:content\/[a-z][a-z0-9-]+\/server$/;
-/**
- * @remarks
- * Content server modules static-import every MDX entry. They must never become
- * browser module-script dependencies discovered from page or component sources.
- */
+import { isContentServerVirtualModule } from '../../build/contracts/content-virtual-modules.js';
+import { parseModuleSource } from '../../cache/module-parse-cache.js';
 export function isBrowserEcopagesVirtualImport(specifier) {
-    return specifier.startsWith('ecopages:') && !CONTENT_SERVER_VIRTUAL_MODULE_PATTERN.test(specifier);
+    return specifier.startsWith('ecopages:') && !isContentServerVirtualModule(specifier);
 }
 /**
  * Extracts runtime `ecopages:` virtual-module imports from a component source file.
@@ -26,7 +20,7 @@ export function extractEcopagesVirtualImports(file) {
     }
     let result;
     try {
-        result = parseSync(file, source, { sourceType: 'module' });
+        result = parseModuleSource(file, source);
     }
     catch {
         return [];

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 canonical file-backed identity 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 identity 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,94 @@
+import path from 'node:path';
+import { rapidhash } from '../../utils/hash.js';
+import { bindComponentIdentity, getComponentIdentity } from '../../eco/component-identity.js';
+/**
+ * Attaches canonical file-backed identity to one component config.
+ */
+export function attachEcoFileMetadataToConfig(config, ownerFile, integrationName) {
+    return bindComponentIdentity({
+        id: getComponentIdentity(config)?.id ?? rapidhash(ownerFile).toString(36),
+        file: ownerFile,
+        integration: getComponentIdentity(config)?.integration ?? integrationName,
+    }, config);
+}
+/**
+ * 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 identity 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 = getComponentIdentity(config)?.file;
+        if (!file) {
+            return;
+        }
+        if (!config) {
+            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/lazy-trigger-planning.js

@@ -1,3 +1,4 @@
+import { getComponentIdentity } from '../../eco/component-identity.js';
 import { rapidhash } from '../../utils/hash.js';
 /**
  * Creates a stable grouping key for a lazy trigger declaration.
@@ -24,7 +25,7 @@ export function getLazyTriggerKey(lazy) {
 export function buildResolvedLazyTriggers(config, groups) {
     if (groups.length === 0)
         return [];
-    const componentFile = config.__eco?.file ?? '';
+    const componentFile = getComponentIdentity(config)?.file ?? '';
     const sortedUrls = groups
         .flatMap((group) => group.scripts)
         .sort()

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

@@ -29,7 +29,6 @@ export declare class PageModuleLoaderService {
      */
     importPageFile(file: string, options?: {
         bypassCache?: boolean;
-        cacheScope?: string;
     }): Promise<EcoPageFile>;
     /**
      * Executes the page's static-props hook with Ecopages runtime context.
@@ -62,8 +61,10 @@ export declare class PageModuleLoaderService {
      */
     resolvePageModule(options: {
         file: string;
+        pageModule?: EcoPageFile;
         importPageFileFn?: (file: string) => Promise<EcoPageFile>;
     }): Promise<{
+        module: EcoPageFile;
         Page: EcoPageFile['default'] | EcoPageComponent<any>;
         getStaticProps?: GetStaticProps<Record<string, unknown>>;
         getMetadata?: GetMetadata;