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

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

@@ -366,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}.`);
         }
@@ -453,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);
     }
     /**
@@ -546,6 +532,7 @@ export class IntegrationRenderer {
     async resolveRouteRenderInputs(routeOptions) {
         const resolvedPageModule = await this.pageModuleLoaderService.resolvePageModule({
             file: routeOptions.file,
+            pageModule: routeOptions.pageModule,
             importPageFileFn: (targetFile) => this.importPageFile(targetFile),
         });
         const { Page, integrationSpecificProps, module: pageModule } = resolvedPageModule;

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/page-browser-graph-session.d.ts

@@ -78,6 +78,7 @@ export declare class SessionPageBrowserGraphCache {
      */
     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, provisionalDependencyPaths: ReadonlySet<string>, build: () => Promise<GraphBuildResult | undefined>): Promise<PageBrowserGraphResult | undefined>;
     resolveGroupedGraph(scope: GroupedGraphScope, build: () => Promise<GroupedGraphBuildOutcome | undefined>): Promise<Map<string, ProcessedAsset[]>>;

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

@@ -139,6 +139,18 @@ export class SessionPageBrowserGraphCache {
         }
         return undefined;
     }
+    getDependencyPathsByRoute(integrationName, routeFile, policy, dependencyInstanceKey = '') {
+        const normalizedRoute = normalizeDependencyPath(routeFile);
+        for (const record of this.records.values()) {
+            if (record.key.integrationName === integrationName &&
+                record.key.policy === policy &&
+                normalizeDependencyPath(record.key.routeFile) === normalizedRoute &&
+                record.key.dependencyInstanceKey === dependencyInstanceKey) {
+                return record.dependencyPaths;
+            }
+        }
+        return undefined;
+    }
     getAffectedGraphIdentities(filePath) {
         const identities = [];
         for (const serializedKey of this.dependencyIndex.getAffectedKeys(filePath)) {

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

@@ -24,6 +24,15 @@ export declare class PageBrowserGraphService {
     private readonly assetProcessingService;
     constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
     resolvePageBrowserGraph(input: PageBrowserGraphResolveInput): Promise<PageBrowserGraphResult | undefined>;
+    /**
+     * Returns dependency paths recorded for one resolved Page Browser Graph.
+     */
+    getDependencyPathsForRoute(input: {
+        integrationName: string;
+        routeFile: string;
+        dependencyInstanceKey?: string;
+        policy?: GraphPolicy;
+    }): ReadonlySet<string> | undefined;
     /**
      * Resolves or builds one Page Browser Graph under the given policy.
      */

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

@@ -23,6 +23,13 @@ export class PageBrowserGraphService {
     async resolvePageBrowserGraph(input) {
         return await this.getOrBuild(input);
     }
+    /**
+     * Returns dependency paths recorded for one resolved Page Browser Graph.
+     */
+    getDependencyPathsForRoute(input) {
+        const policy = input.policy ?? this.resolveGraphPolicy();
+        return getAppPageBrowserGraphSession(this.appConfig).getDependencyPathsByRoute(input.integrationName, input.routeFile, policy, input.dependencyInstanceKey ?? '');
+    }
     /**
      * Resolves or builds one Page Browser Graph under the given policy.
      */

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

@@ -1,3 +1,5 @@
+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';
@@ -6,6 +8,7 @@ import { mergePageBrowserGraphContributions } from '../page-browser-graph/page-b
 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.
  *
@@ -35,7 +38,7 @@ export class RouteRenderOrchestrator {
      * HTML transformation.
      */
     async prepareRenderOptions(routeOptions, adapter) {
-        const resolvedInputs = await adapter.resolveRouteRenderInputs(routeOptions);
+        const resolvedInputs = await measureRouteRenderPhase('resolve-route-inputs', () => adapter.resolveRouteRenderInputs(routeOptions));
         const finalProps = {
             ...resolvedInputs.props,
             ...(routeOptions.props ?? {}),
@@ -45,15 +48,17 @@ export class RouteRenderOrchestrator {
             props: finalProps,
         };
         const { Page, HtmlTemplate, Layouts } = finalResolvedInputs;
-        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' },
-            ],
+        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 dependencyInstanceKey = createPageDependencyInstanceKey({
             params: routeOptions.params,
@@ -68,17 +73,20 @@ export class RouteRenderOrchestrator {
             dependencyInstanceKey,
         };
         const resolvedPageDependencies = await adapter.resolvePageDependencies(graphContext);
-        const [{ resolvedDependencies }, pageBrowserGraph] = await Promise.all([
-            adapter.resolveRouteDependencies({
-                components: componentsToResolve,
-            }),
-            this.pageBrowserGraphService.resolvePageBrowserGraph({
-                routeFile: routeOptions.file,
-                dependencyInstanceKey,
-                integrationName: adapter.name,
-                collectContribution: async () => mergePageBrowserGraphContributions(await adapter.collectPageBrowserGraphContribution(graphContext), resolvedPageDependencies?.contribution),
-            }),
-        ]);
+        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,
@@ -92,15 +100,24 @@ export class RouteRenderOrchestrator {
             buildEagerSsrLazyAssetsFromGraph(this.assetProcessingService, componentsToResolve, adapter.name),
         ]);
         allDependencies.push(...globalAssets, ...eagerSsrLazyAssets);
-        return buildPreparedRenderOptions({
-            routeOptions,
-            resolvedInputs: finalResolvedInputs,
-            resolvedPageDependencyComponents,
-            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);
@@ -127,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;
@@ -137,27 +154,29 @@ export class RouteRenderOrchestrator {
         const canReuseCapturedBody = !hasUnresolvedMarkerHtml && htmlFinalization.finalizeHtml === undefined;
         if (canReuseCapturedBody) {
             const responseBody = typeof renderExecution.body === 'string' ? renderExecution.body : renderExecution.html;
-            const body = await adapter.transformRouteResponse(new Response(responseBody, {
+            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) {
@@ -181,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

@@ -1,7 +1,7 @@
 import type { EcoComponent, EcoComponentConfig, EcoComponentDependencies } from '../../types/public-types.js';
 import type { PageDependenciesResult } from '../../eco/eco.types.js';
 /**
- * Attaches file-backed `__eco` metadata to one component config.
+ * Attaches canonical file-backed identity to one component config.
  */
 export declare function attachEcoFileMetadataToConfig(config: EcoComponentConfig, ownerFile: string, integrationName: string): EcoComponentConfig;
 /**
@@ -26,7 +26,7 @@ export type CollectComponentConfigFilePathsOptions = {
     includeLayouts?: boolean;
 };
 /**
- * Walks component configs and collects every resolved `config.__eco.file` path.
+ * Walks component configs and collects every resolved identity file path.
  */
 export declare function collectComponentConfigFilePaths(components: ReadonlyArray<EcoComponent | Partial<EcoComponent> | undefined>, options?: CollectComponentConfigFilePathsOptions): Set<string>;
 /**

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

@@ -1,17 +1,15 @@
 import path from 'node:path';
 import { rapidhash } from '../../utils/hash.js';
+import { bindComponentIdentity, getComponentIdentity } from '../../eco/component-identity.js';
 /**
- * Attaches file-backed `__eco` metadata to one component config.
+ * Attaches canonical file-backed identity to one component config.
  */
 export function attachEcoFileMetadataToConfig(config, ownerFile, integrationName) {
-    return {
-        ...config,
-        __eco: {
-            id: config.__eco?.id ?? rapidhash(ownerFile).toString(36),
-            file: ownerFile,
-            integration: config.__eco?.integration ?? integrationName,
-        },
-    };
+    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
@@ -45,7 +43,7 @@ export function collectFileScopedDependencyComponents(options) {
     return components;
 }
 /**
- * Walks component configs and collects every resolved `config.__eco.file` path.
+ * Walks component configs and collects every resolved identity file path.
  */
 export function collectComponentConfigFilePaths(components, options) {
     const files = new Set();
@@ -54,10 +52,13 @@ export function collectComponentConfigFilePaths(components, options) {
         files.add(path.resolve(additionalPath));
     }
     const visit = (config) => {
-        const file = config?.__eco?.file;
+        const file = getComponentIdentity(config)?.file;
         if (!file) {
             return;
         }
+        if (!config) {
+            return;
+        }
         const resolved = path.resolve(file);
         if (visited.has(resolved)) {
             return;

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,6 +61,7 @@ export declare class PageModuleLoaderService {
      */
     resolvePageModule(options: {
         file: string;
+        pageModule?: EcoPageFile;
         importPageFileFn?: (file: string) => Promise<EcoPageFile>;
     }): Promise<{
         module: EcoPageFile;

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

@@ -1,6 +1,7 @@
 import { invariant } from '../../utils/invariant.js';
 import { getAppModuleLoader } from '../../services/module-loading/app-server-module-transpiler.service.js';
 import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.js';
+import { HttpError } from '../../errors/http-error.js';
 /**
  * Loads route page modules and normalizes their data hooks for rendering.
  *
@@ -39,7 +40,6 @@ export class PageModuleLoaderService {
                 rootDir: this.appConfig.rootDir,
                 outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
                 bypassCache: options?.bypassCache,
-                cacheScope: options?.cacheScope,
                 transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
                 noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`,
             });
@@ -65,7 +65,11 @@ export class PageModuleLoaderService {
             })
                 .then((data) => data)
                 .catch((err) => {
-                throw new Error(`Error fetching static props: ${err.message}`);
+                if (HttpError.isHttpError(err) || err instanceof Response) {
+                    throw err;
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`Error fetching static props: ${message}`, { cause: err });
             })
             : {
                 props: {},
@@ -98,7 +102,8 @@ export class PageModuleLoaderService {
      * When both component static methods and module exports exist, component statics win.
      */
     async resolvePageModule(options) {
-        const module = await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file);
+        const module = options.pageModule ??
+            (await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file));
         const { default: Page, getStaticProps: moduleGetStaticProps, getMetadata: moduleGetMetadata, ...integrationSpecificProps } = module;
         return {
             module,