@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

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

@@ -0,0 +1,229 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import {
+} from "../../../services/assets/asset-processing-service/index.js";
+import { appLogger } from "../../../global/app-logger.js";
+import { startupTrace } from "../../../diagnostics/startup-trace.js";
+import {
+  collectPageBrowserGraphDependencyPaths,
+  createPageBrowserGraphEntryFingerprint,
+  getAppPageBrowserGraphSession
+} from "./page-browser-graph-session.js";
+function isGroupedContentScriptAsset(asset) {
+  return asset.kind === "script" && asset.source === "content" && Boolean(asset.groupedBundle?.id);
+}
+function getGroupedBundleAssetKey(groupedBundle) {
+  return `${groupedBundle.id}:${groupedBundle.entryName}`;
+}
+class PageBrowserGraphService {
+  appConfig;
+  assetProcessingService;
+  constructor(appConfig, assetProcessingService) {
+    this.appConfig = appConfig;
+    this.assetProcessingService = assetProcessingService;
+  }
+  async resolvePageBrowserGraph(input) {
+    return await this.getOrBuild(input);
+  }
+  /**
+   * Resolves or builds one Page Browser Graph under the given policy.
+   */
+  async getOrBuild(input) {
+    const policy = input.policy ?? this.resolveGraphPolicy();
+    const session = getAppPageBrowserGraphSession(this.appConfig);
+    if (!this.isHmrEnabled()) {
+      const cachedByRoute = session.getGraphByRoute(input.integrationName, input.routeFile, policy);
+      if (cachedByRoute) {
+        return cachedByRoute;
+      }
+    }
+    const contribution = await input.collectContribution(input.routeFile);
+    if (!contribution) {
+      return void 0;
+    }
+    const entryFingerprint = createPageBrowserGraphEntryFingerprint(contribution);
+    return await session.resolveGraph(
+      {
+        integrationName: input.integrationName,
+        routeFile: input.routeFile,
+        entryFingerprint,
+        policy
+      },
+      async () => this.buildPageBrowserGraphRecord(input, contribution)
+    );
+  }
+  resolveGraphPolicy() {
+    return this.isHmrEnabled() ? "development" : "production";
+  }
+  isHmrEnabled() {
+    return typeof this.assetProcessingService.getHmrManager === "function" && this.assetProcessingService.getHmrManager()?.isEnabled() === true;
+  }
+  async buildPageBrowserGraphRecord(input, contribution) {
+    const result = await this.materializePageBrowserGraph(input, contribution);
+    if (!result) {
+      return void 0;
+    }
+    startupTrace.markFirstPageBrowserGraphReady(getAppPageBrowserGraphSession(this.appConfig).getBuildCount());
+    return result;
+  }
+  async materializePageBrowserGraph(input, contribution) {
+    const groupedDependencies = (contribution.dependencies ?? []).filter((dep) => isGroupedContentScriptAsset(dep));
+    const ungroupedDependencies = (contribution.dependencies ?? []).filter(
+      (dep) => !isGroupedContentScriptAsset(dep)
+    );
+    const groupedAssets = groupedDependencies.length ? (await this.resolveGroupedPageBrowserAssets(input, contribution)).assetsByRoute.get(input.routeFile) ?? [] : [];
+    const processedDependencies = ungroupedDependencies.length ? await this.assetProcessingService.processDependencies(
+      ungroupedDependencies,
+      `${input.integrationName}:${input.routeFile}`
+    ) : [];
+    const resolvedAssets = [...processedDependencies, ...groupedAssets, ...contribution.assets ?? []];
+    const result = this.partitionPageBrowserGraphAssets(resolvedAssets);
+    const dependencyPaths = collectPageBrowserGraphDependencyPaths(input.routeFile, contribution, resolvedAssets);
+    return {
+      result,
+      dependencyPaths
+    };
+  }
+  async resolveGroupedPageBrowserAssets(input, currentContribution) {
+    if (this.isHmrEnabled()) {
+      return await this.buildGroupedPageBrowserAssets(input, currentContribution);
+    }
+    const session = getAppPageBrowserGraphSession(this.appConfig);
+    const assetsByRoute = await session.resolveGroupedGraph(input.integrationName, async () => {
+      const built = await this.buildGroupedPageBrowserAssets(input, currentContribution);
+      if (built.hasCollectionFailures) {
+        return {
+          skipCache: true,
+          assetsByRoute: built.assetsByRoute,
+          dependencyPaths: built.dependencyPaths
+        };
+      }
+      return {
+        assetsByRoute: built.assetsByRoute,
+        dependencyPaths: built.dependencyPaths,
+        generation: 0
+      };
+    });
+    return {
+      assetsByRoute,
+      dependencyPaths: /* @__PURE__ */ new Set(),
+      hasCollectionFailures: false
+    };
+  }
+  async buildGroupedPageBrowserAssets(input, currentContribution) {
+    const routeFiles = this.isHmrEnabled() ? [input.routeFile] : await this.listIntegrationRouteFiles(input.integrationName);
+    const currentRouteGroupedDependencies = (currentContribution.dependencies ?? []).filter(
+      (dep) => isGroupedContentScriptAsset(dep)
+    );
+    const groupedDependencies = [...currentRouteGroupedDependencies];
+    const groupedAssetKeysByRoute = /* @__PURE__ */ new Map();
+    const dependencyPaths = /* @__PURE__ */ new Set([path.resolve(input.routeFile)]);
+    let hasCollectionFailures = false;
+    if (currentRouteGroupedDependencies.length > 0) {
+      groupedAssetKeysByRoute.set(
+        input.routeFile,
+        new Set(currentRouteGroupedDependencies.map((dep) => getGroupedBundleAssetKey(dep.groupedBundle)))
+      );
+    }
+    for (const routeFile of routeFiles) {
+      if (routeFile === input.routeFile) {
+        continue;
+      }
+      let contribution;
+      try {
+        contribution = await input.collectContribution(routeFile);
+      } catch (error) {
+        hasCollectionFailures = true;
+        appLogger.warn(
+          `Skipping grouped page-browser contribution for ${routeFile}: ${error instanceof Error ? error.message : String(error)}`
+        );
+        continue;
+      }
+      if (!contribution?.dependencies?.length) {
+        continue;
+      }
+      const routeGroupedDependencies = contribution.dependencies.filter(
+        (dep) => isGroupedContentScriptAsset(dep)
+      );
+      if (routeGroupedDependencies.length === 0) {
+        continue;
+      }
+      groupedDependencies.push(...routeGroupedDependencies);
+      groupedAssetKeysByRoute.set(
+        routeFile,
+        new Set(routeGroupedDependencies.map((dep) => getGroupedBundleAssetKey(dep.groupedBundle)))
+      );
+      dependencyPaths.add(path.resolve(routeFile));
+    }
+    if (groupedDependencies.length === 0) {
+      return {
+        assetsByRoute: /* @__PURE__ */ new Map(),
+        dependencyPaths,
+        hasCollectionFailures
+      };
+    }
+    for (const dependency of groupedDependencies) {
+      if (dependency.source === "file") {
+        dependencyPaths.add(path.resolve(dependency.filepath));
+      }
+    }
+    const processedGroupedDependencies = await this.assetProcessingService.processDependencies(
+      groupedDependencies,
+      `${input.integrationName}:grouped-page-browser-graph`
+    );
+    const groupedAssetsByRoute = /* @__PURE__ */ new Map();
+    for (const [routeFile, groupedAssetKeys] of groupedAssetKeysByRoute) {
+      const matchedAssets = processedGroupedDependencies.filter((asset) => {
+        if (!asset.groupedBundle) {
+          return false;
+        }
+        return groupedAssetKeys.has(getGroupedBundleAssetKey(asset.groupedBundle));
+      });
+      if (groupedAssetKeys.size > 0 && matchedAssets.length === 0) {
+        appLogger.warn(
+          `Grouped page-browser assets for ${routeFile} are missing groupedBundle metadata after processing. Hydration scripts may be omitted from HTML.`
+        );
+      }
+      groupedAssetsByRoute.set(routeFile, matchedAssets);
+    }
+    for (const asset of processedGroupedDependencies) {
+      if (asset.sourceFilepath) {
+        dependencyPaths.add(path.resolve(asset.sourceFilepath));
+      }
+      for (const bundledSourceFilepath of asset.bundledSourceFilepaths ?? []) {
+        dependencyPaths.add(path.resolve(bundledSourceFilepath));
+      }
+    }
+    return {
+      assetsByRoute: groupedAssetsByRoute,
+      dependencyPaths,
+      hasCollectionFailures
+    };
+  }
+  async listIntegrationRouteFiles(integrationName) {
+    const integration = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
+    if (!integration) {
+      return [];
+    }
+    const scannedFiles = await fileSystem.glob(
+      integration.extensions.map((extension) => `**/*${extension}`),
+      { cwd: this.appConfig.absolutePaths.pagesDir }
+    );
+    return scannedFiles.filter((file) => !file.includes(".ecopages-node.")).map((file) => path.join(this.appConfig.absolutePaths.pagesDir, file)).sort((left, right) => left.localeCompare(right));
+  }
+  partitionPageBrowserGraphAssets(assets) {
+    const entryAssets = [];
+    const chunkAssets = [];
+    for (const asset of assets) {
+      if (asset.packageRole === "dynamic-chunk") {
+        chunkAssets.push(asset);
+        continue;
+      }
+      entryAssets.push(asset);
+    }
+    return { entryAssets, chunkAssets };
+  }
+}
+export {
+  PageBrowserGraphService
+};

package/src/route-renderer/orchestration/{processed-asset-dedupe.d.ts → page-browser-graph/processed-asset-dedupe.d.ts}

@@ -1,3 +1,3 @@
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
 export declare function buildProcessedAssetDedupeKey(asset: ProcessedAsset): string;
 export declare function dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];

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

@@ -0,0 +1,31 @@
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import type { EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PagePackageResult, RouteRendererBody, RouteRendererOptions } from '../../../types/public-types.js';
+import type { RouteHtmlFinalization, RouteRenderOrchestratorAdapter, RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
+/**
+ * Host surface required to build the orchestrator adapter for one integration renderer.
+ */
+export type IntegrationRouteRenderAdapterHost<C> = {
+    readonly name: string;
+    resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
+    resolveRouteDependencies(input: {
+        components: (EcoComponent | Partial<EcoComponent>)[];
+    }): Promise<{
+        resolvedDependencies: ProcessedAsset[];
+    }>;
+    importPageFile(file: string): Promise<EcoPageFile>;
+    collectPageBrowserGraphContribution(context: PageBrowserGraphContributionContext): Promise<PageBrowserGraphContribution | undefined>;
+    renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    getDocumentAttributes(renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
+    getHtmlDocumentContributions(options: {
+        renderOptions: IntegrationRendererRenderOptions<C>;
+        partial: boolean;
+    }): HtmlDocumentContribution[] | undefined;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+    transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<RouteRendererBody>;
+};
+/**
+ * Builds the internal route-render adapter consumed by `RouteRenderOrchestrator`.
+ */
+export declare function createIntegrationRouteRenderAdapter<C>(host: IntegrationRouteRenderAdapterHost<C>): RouteRenderOrchestratorAdapter<C>;
+export type { RouteHtmlFinalization };

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

@@ -0,0 +1,25 @@
+import { loadPageBrowserGraphContribution } from "../page-browser-graph/page-browser-graph-contribution.loader.js";
+import { buildRouteHtmlFinalization } from "./route-html-finalization.service.js";
+function createIntegrationRouteRenderAdapter(host) {
+  return {
+    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)
+    ),
+    renderRouteBody: (renderOptions) => host.renderRouteBody(renderOptions),
+    getRouteHtmlFinalization: (renderOptions) => buildRouteHtmlFinalization({
+      renderOptions,
+      getDocumentAttributes: (options) => host.getDocumentAttributes(options),
+      getHtmlDocumentContributions: (options) => host.getHtmlDocumentContributions(options),
+      applyAttributesToHtmlElement: (html, attributes) => host.applyAttributesToHtmlElement(html, attributes)
+    }),
+    transformRouteResponse: (response, htmlContributions, pagePackage) => host.transformRouteResponse(response, htmlContributions, pagePackage)
+  };
+}
+export {
+  createIntegrationRouteRenderAdapter
+};

package/src/route-renderer/orchestration/route-pipeline/marker-artifact.utils.d.ts

@@ -0,0 +1,6 @@
+export declare function decodeHtmlEntities(value: string): string;
+export declare function normalizeUnresolvedMarkerArtifactHtml(html: string): string;
+export declare function inspectUnresolvedMarkerArtifactHtml(html: string): {
+    hasUnresolvedMarkerArtifacts: boolean;
+    normalizedHtml: string;
+};

package/src/route-renderer/orchestration/route-pipeline/marker-artifact.utils.js

@@ -0,0 +1,27 @@
+function decodeHtmlEntities(value) {
+  let decoded = value;
+  let previous;
+  do {
+    previous = decoded;
+    decoded = decoded.replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&#x27;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+  } while (decoded !== previous);
+  return decoded;
+}
+function normalizeUnresolvedMarkerArtifactHtml(html) {
+  return html.replace(
+    /&(?:amp;)?lt;eco-marker\b[\s\S]*?&(?:amp;)?gt;&(?:amp;)?lt;\/eco-marker&(?:amp;)?gt;/g,
+    (marker) => decodeHtmlEntities(marker)
+  );
+}
+function inspectUnresolvedMarkerArtifactHtml(html) {
+  const normalizedHtml = normalizeUnresolvedMarkerArtifactHtml(html);
+  return {
+    normalizedHtml,
+    hasUnresolvedMarkerArtifacts: normalizedHtml.includes("<eco-marker")
+  };
+}
+export {
+  decodeHtmlEntities,
+  inspectUnresolvedMarkerArtifactHtml,
+  normalizeUnresolvedMarkerArtifactHtml
+};

package/src/route-renderer/orchestration/route-pipeline/robots-meta.contribution.d.ts

@@ -0,0 +1,15 @@
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import type { PageMetadataProps, PageRobotsMetadata } from '../../../types/public-types.js';
+/**
+ * Builds a head contribution for non-default `metadata.robots` values.
+ *
+ * @remarks
+ * When `robots` is omitted or matches the default `index,follow` behaviour,
+ * no tag is emitted (Next.js parity). Otherwise a single
+ * `<meta name="robots" content="...">` contribution is returned.
+ */
+export declare function buildRobotsMetaContribution(metadata: Pick<PageMetadataProps, 'robots'>): HtmlDocumentContribution | undefined;
+/**
+ * Formats robots directives for a meta tag, or `undefined` when defaults apply.
+ */
+export declare function formatRobotsMetaContent(robots: PageRobotsMetadata | undefined): string | undefined;

package/src/route-renderer/orchestration/route-pipeline/robots-meta.contribution.js

@@ -0,0 +1,36 @@
+import { escapeHtmlAttribute } from "../../../utils/html-escaping.js";
+function buildRobotsMetaContribution(metadata) {
+  const content = formatRobotsMetaContent(metadata.robots);
+  if (!content) {
+    return void 0;
+  }
+  return {
+    placement: "head-append",
+    html: `<meta name="robots" content="${escapeHtmlAttribute(content)}">`
+  };
+}
+function formatRobotsMetaContent(robots) {
+  if (!robots) {
+    return void 0;
+  }
+  const index = robots.index !== false;
+  const follow = robots.follow !== false;
+  const directives = [];
+  if (!index) {
+    directives.push("noindex");
+  }
+  if (!follow) {
+    directives.push("nofollow");
+  }
+  if (robots.nocache) {
+    directives.push("nocache");
+  }
+  if (directives.length === 0) {
+    return void 0;
+  }
+  return directives.join(", ");
+}
+export {
+  buildRobotsMetaContribution,
+  formatRobotsMetaContent
+};

package/src/route-renderer/orchestration/route-pipeline/route-html-finalization.service.d.ts

@@ -0,0 +1,20 @@
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import type { IntegrationRendererRenderOptions } from '../../../types/public-types.js';
+import type { RouteHtmlFinalization } from './route-render-orchestrator.js';
+export type RouteHtmlFinalizationContext<C> = {
+    renderOptions: IntegrationRendererRenderOptions<C>;
+    getDocumentAttributes: (renderOptions: IntegrationRendererRenderOptions<C>) => Record<string, string> | undefined;
+    getHtmlDocumentContributions: (options: {
+        renderOptions: IntegrationRendererRenderOptions<C>;
+        partial: boolean;
+    }) => HtmlDocumentContribution[] | undefined;
+    applyAttributesToHtmlElement: (html: string, attributes: Record<string, string>) => string;
+};
+/**
+ * Builds the structural HTML finalization plan for one prepared route render.
+ *
+ * @remarks
+ * Merges core robots meta contributions with integration-owned document
+ * contributions so page-level `metadata.robots` works across templates.
+ */
+export declare function buildRouteHtmlFinalization<C>(context: RouteHtmlFinalizationContext<C>): RouteHtmlFinalization;

package/src/route-renderer/orchestration/route-pipeline/route-html-finalization.service.js

@@ -0,0 +1,24 @@
+import { buildRobotsMetaContribution } from "./robots-meta.contribution.js";
+function buildRouteHtmlFinalization(context) {
+  const { renderOptions } = context;
+  const documentAttributes = context.getDocumentAttributes(renderOptions);
+  const integrationContributions = context.getHtmlDocumentContributions({ renderOptions, partial: false }) ?? [];
+  const robotsContribution = buildRobotsMetaContribution(renderOptions.metadata ?? {});
+  const htmlContributions = robotsContribution ? [robotsContribution, ...integrationContributions] : integrationContributions;
+  const hasStructuralFinalization = documentAttributes && Object.keys(documentAttributes).length > 0;
+  if (!hasStructuralFinalization && htmlContributions.length === 0) {
+    return {};
+  }
+  return {
+    htmlContributions,
+    finalizeHtml: (html) => {
+      if (!documentAttributes || Object.keys(documentAttributes).length === 0) {
+        return html;
+      }
+      return context.applyAttributesToHtmlElement(html, documentAttributes);
+    }
+  };
+}
+export {
+  buildRouteHtmlFinalization
+};

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

@@ -0,0 +1,25 @@
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphResult, PageMetadataProps, EcoPageLayoutEntry, RouteRendererOptions } from '../../../types/public-types.js';
+import { type ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+type PreparedRenderInputs = {
+    Page: EcoPageFile['default'] | EcoPageComponent<any>;
+    HtmlTemplate: EcoComponent<HtmlTemplateProps>;
+    Layouts: EcoComponent[];
+    Layout?: EcoComponent;
+    layoutEntries?: EcoPageLayoutEntry[];
+    props: Record<string, unknown>;
+    metadata: PageMetadataProps;
+    integrationSpecificProps: Record<string, unknown>;
+};
+/**
+ * Assembles the final integration render options after route prep dependencies resolve.
+ */
+export declare function buildPreparedRenderOptions<C = unknown>(input: {
+    routeOptions: RouteRendererOptions;
+    resolvedInputs: PreparedRenderInputs;
+    resolvedDependencies: ProcessedAsset[];
+    allDependencies: ProcessedAsset[];
+    pageBrowserGraph?: PageBrowserGraphResult;
+    appConfig: EcoPagesAppConfig;
+}): IntegrationRendererRenderOptions<C>;
+export {};

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

@@ -0,0 +1,49 @@
+import { createPagePackage } from "../../../services/assets/asset-processing-service/index.js";
+import { dedupeProcessedAssets } from "../page-browser-graph/processed-asset-dedupe.js";
+import { createPageLocalsProxy } from "./route-prepared-options.utils.js";
+function buildPreparedRenderOptions(input) {
+  const { routeOptions, resolvedInputs, 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 pageProps = {
+    ...resolvedProps,
+    params: routeOptions.params || {},
+    query: routeOptions.query || {}
+  };
+  const cacheStrategy = Page.cache;
+  const defaultCacheStrategy = appConfig.cache?.defaultStrategy ?? "static";
+  const effectiveCacheStrategy = cacheStrategy ?? defaultCacheStrategy;
+  const localsAvailable = effectiveCacheStrategy === "dynamic" && routeOptions.locals !== void 0;
+  const pageLocals = localsAvailable ? routeOptions.locals : createPageLocalsProxy(routeOptions.file);
+  const locals = localsAvailable ? routeOptions.locals : void 0;
+  const preparedOptions = {
+    ...routeOptions,
+    resolvedDependencies,
+    pagePackage,
+    HtmlTemplate,
+    Layouts,
+    Layout,
+    layoutEntries,
+    props: resolvedProps,
+    Page,
+    metadata,
+    params: routeOptions.params || {},
+    query: routeOptions.query || {},
+    pageProps,
+    locals,
+    pageLocals,
+    cacheStrategy
+  };
+  return {
+    ...integrationSpecificProps,
+    ...preparedOptions
+  };
+}
+export {
+  buildPreparedRenderOptions
+};

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

@@ -0,0 +1,4 @@
+/**
+ * Proxy that throws when dynamic route locals are accessed on non-dynamic pages.
+ */
+export declare function createPageLocalsProxy(filePath: string): Record<string, never>;

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

@@ -0,0 +1,33 @@
+import { LocalsAccessError } from "../../../errors/locals-access-error.js";
+function createPageLocalsProxy(filePath) {
+  const errorMessage = `[ecopages] Request locals are only available during request-time rendering with cache: 'dynamic'. Page: ${filePath}. If you meant to use locals here, set cache: 'dynamic' and provide locals from route middleware/handlers.`;
+  return new Proxy(
+    {},
+    {
+      get: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      set: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      has: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      ownKeys: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      deleteProperty: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      defineProperty: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      getOwnPropertyDescriptor: () => {
+        throw new LocalsAccessError(errorMessage);
+      }
+    }
+  );
+}
+export {
+  createPageLocalsProxy
+};

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

@@ -1,13 +1,15 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
-import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
-import { OwnershipValidationService } from './ownership-validation.service.js';
-import { OwnershipPlanningService } from './ownership-planning.service.js';
+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 { 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';
 export type RouteRenderOrchestratorResolvedInputs = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
     HtmlTemplate: EcoComponent<HtmlTemplateProps>;
+    Layouts: EcoComponent[];
     Layout?: EcoComponent;
+    layoutEntries?: EcoPageLayoutEntry[];
     props: Record<string, unknown>;
     metadata: PageMetadataProps;
     integrationSpecificProps: Record<string, unknown>;
@@ -44,15 +46,6 @@ export interface RouteRenderOrchestratorAdapter<C> {
      * Collects declarative Page Browser Graph requirements for one route.
      */
     collectPageBrowserGraphContribution(routeFile: string): Promise<PageBrowserGraphContribution | undefined>;
-    /**
-     * Resolves the optional page-root render through the foreign-child-aware component contract.
-     */
-    resolveRoutePageComponentRender(input: {
-        Page: EcoComponent;
-        Layout?: EcoComponent;
-        props: Record<string, unknown>;
-        routeOptions: RouteRendererOptions;
-    }): Promise<ComponentRenderResult | undefined>;
     /**
      * Executes the Integration-specific route render.
      */
@@ -64,7 +57,7 @@ export interface RouteRenderOrchestratorAdapter<C> {
     /**
      * Runs SSR-policy response transformation and returns the body value exposed to callers.
      */
-    transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
+    transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[], pagePackage?: IntegrationRendererRenderOptions<C>['pagePackage']): Promise<RouteRendererBody>;
 }
 /**
  * Captured route-render output in both replayable body and string HTML forms.
@@ -77,8 +70,8 @@ export interface CapturedHtmlRenderResult {
  * Optional app-scoped collaborators used by the route render orchestrator.
  */
 export interface RouteRenderOrchestratorDependencies {
-    ownershipPlanningService?: OwnershipPlanningService;
     ownershipValidationService?: OwnershipValidationService;
+    pageBrowserGraphService?: PageBrowserGraphService;
 }
 /**
  * Owns one route render from normalized module loading through final HTML output.
@@ -91,17 +84,15 @@ export interface RouteRenderOrchestratorDependencies {
 export declare class RouteRenderOrchestrator {
     private readonly appConfig;
     private readonly assetProcessingService;
-    private readonly ownershipPlanningService;
     private readonly ownershipValidationService;
-    private readonly pageBrowserGraphCache;
-    private readonly groupedPageBrowserGraphCache;
+    private readonly pageBrowserGraphService;
     constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService, dependencies?: RouteRenderOrchestratorDependencies);
     /**
      * Builds normalized route render options before the integration render runs.
      *
      * This preparation step validates route-root ownership, resolves page data,
-     * collects processed assets, captures optional page-root render metadata, and
-     * produces the page package consumed by downstream HTML transformation.
+     * collects processed assets, and produces the page package consumed by downstream
+     * HTML transformation.
      */
     prepareRenderOptions<C = unknown>(routeOptions: RouteRendererOptions, adapter: RouteRenderOrchestratorAdapter<C>): Promise<IntegrationRendererRenderOptions<C>>;
     resolveDeclaredPageBrowserGraph(input: {
@@ -109,31 +100,6 @@ export declare class RouteRenderOrchestrator {
         integrationName: string;
         collectContribution: (routeFile: string) => Promise<PageBrowserGraphContribution | undefined>;
     }): Promise<PageBrowserGraphResult | undefined>;
-    private resolvePageBrowserGraph;
-    private isHmrEnabled;
-    private buildPageBrowserGraph;
-    /**
-     * Resolves grouped page-browser assets for all routes owned by one integration.
-     *
-     * @remarks
-     * This keeps one shared browser-build result available across sibling routes so
-     * navigation can reuse the same emitted client graph instead of rebuilding one
-     * page entry at a time. HMR bypasses this cache because the grouped build must
-     * reflect the latest source on every request.
-     */
-    private resolveGroupedPageBrowserAssets;
-    /**
-     * Builds the shared grouped page-browser asset map for one integration.
-     *
-     * @remarks
-     * Each route can declare grouped content-script dependencies that should be
-     * emitted together. This method collects those declarations across the owning
-     * integration, runs the grouped processor once, and then maps the emitted
-     * assets back onto the routes that reference them.
-     */
-    private buildGroupedPageBrowserAssets;
-    private listIntegrationRouteFiles;
-    private partitionPageBrowserGraphAssets;
     /**
      * Captures one route render body as HTML while preserving a replayable body value.
      */
@@ -147,10 +113,4 @@ export declare class RouteRenderOrchestrator {
      */
     executePrepared<C = unknown>(renderOptions: IntegrationRendererRenderOptions<C>, adapter: RouteRenderOrchestratorAdapter<C>): Promise<RouteRenderResult>;
     private captureRenderedBody;
-    private collectResolvedTriggers;
-    private collectUsedIntegrationDependencies;
-    private collectIntegrationNames;
-    private buildGlobalInjectorAssets;
-    private buildEagerSsrLazyAssets;
-    private collectEagerSsrLazyDependencies;
 }