@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

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

@@ -0,0 +1,248 @@
+import path from 'node:path';
+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';
+import { createRouteGraphLookupKey } from './route-instance-key.js';
+function isGroupedContentScriptAsset(asset) {
+    return asset.kind === 'script' && asset.source === 'content' && Boolean(asset.groupedBundle?.id);
+}
+function getGroupedBundleAssetKey(groupedBundle) {
+    return `${groupedBundle.id}:${groupedBundle.entryName}`;
+}
+function indexGroupedAssetsByBundleKey(processedAssets) {
+    const assetsByBundleKey = new Map();
+    for (const [index, asset] of processedAssets.entries()) {
+        if (!asset.groupedBundle) {
+            continue;
+        }
+        const bundleKey = getGroupedBundleAssetKey(asset.groupedBundle);
+        const assets = assetsByBundleKey.get(bundleKey);
+        if (assets) {
+            assets.push({ asset, index });
+        }
+        else {
+            assetsByBundleKey.set(bundleKey, [{ asset, index }]);
+        }
+    }
+    return assetsByBundleKey;
+}
+/**
+ * Resolves declarative page browser graph assets for one route and integration.
+ */
+export class PageBrowserGraphService {
+    appConfig;
+    assetProcessingService;
+    constructor(appConfig, assetProcessingService) {
+        this.appConfig = appConfig;
+        this.assetProcessingService = assetProcessingService;
+    }
+    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.
+     */
+    async getOrBuild(input) {
+        const policy = input.policy ?? this.resolveGraphPolicy();
+        const session = getAppPageBrowserGraphSession(this.appConfig);
+        const dependencyInstanceKey = input.dependencyInstanceKey ?? '';
+        if (!this.isHmrEnabled()) {
+            const cachedByRoute = session.getGraphByRoute(input.integrationName, input.routeFile, policy, dependencyInstanceKey);
+            if (cachedByRoute) {
+                return cachedByRoute;
+            }
+        }
+        const contribution = await input.collectContribution();
+        if (!contribution) {
+            return undefined;
+        }
+        const entryFingerprint = createPageBrowserGraphEntryFingerprint(contribution);
+        return await session.resolveGraph({
+            integrationName: input.integrationName,
+            routeFile: input.routeFile,
+            dependencyInstanceKey,
+            entryFingerprint,
+            policy,
+        }, collectPageBrowserGraphDependencyPaths(input.routeFile, contribution, contribution.assets ?? []), 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 undefined;
+        }
+        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 groupedResolution = groupedDependencies.length
+            ? await this.resolveGroupedPageBrowserAssets(input, contribution)
+            : undefined;
+        const groupedAssets = groupedResolution?.assetsByRoute.get(createRouteGraphLookupKey(input.routeFile, input.dependencyInstanceKey ?? '')) ?? [];
+        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,
+            cacheable: groupedResolution?.cacheable ?? true,
+        };
+    }
+    async resolveGroupedPageBrowserAssets(input, currentContribution) {
+        if (this.isHmrEnabled()) {
+            return await this.buildGroupedPageBrowserAssets(input, currentContribution);
+        }
+        if (!input.groupedBuildPlan) {
+            const built = await this.buildGroupedPageBrowserAssets(input, currentContribution);
+            return {
+                ...built,
+                cacheable: false,
+            };
+        }
+        const session = getAppPageBrowserGraphSession(this.appConfig);
+        const groupedScope = {
+            integrationName: input.integrationName,
+            planKey: input.groupedBuildPlan.planKey,
+        };
+        let groupedCacheable = true;
+        const assetsByRoute = await session.resolveGroupedGraph(groupedScope, async () => {
+            const built = await this.buildGroupedPageBrowserAssets(input, currentContribution);
+            groupedCacheable = !built.hasCollectionFailures;
+            if (built.hasCollectionFailures) {
+                return {
+                    skipCache: true,
+                    assetsByRoute: built.assetsByRoute,
+                    dependencyPaths: built.dependencyPaths,
+                };
+            }
+            return {
+                assetsByRoute: built.assetsByRoute,
+                dependencyPaths: built.dependencyPaths,
+                generation: 0,
+            };
+        });
+        return {
+            assetsByRoute,
+            dependencyPaths: new Set(),
+            hasCollectionFailures: !groupedCacheable,
+            cacheable: groupedCacheable,
+        };
+    }
+    async buildGroupedPageBrowserAssets(input, currentContribution) {
+        const dependencyInstanceKey = input.dependencyInstanceKey ?? '';
+        const currentRouteLookupKey = createRouteGraphLookupKey(input.routeFile, dependencyInstanceKey);
+        const groupedCollection = input.groupedBuildPlan
+            ? {
+                contributions: input.groupedBuildPlan.instances.map((instance) => ({
+                    routeFile: instance.routeFile,
+                    dependencyInstanceKey: instance.dependencyInstanceKey,
+                    contribution: instance.contribution,
+                })),
+                hasCollectionFailures: false,
+            }
+            : {
+                contributions: [],
+                hasCollectionFailures: false,
+            };
+        const groupedContributions = groupedCollection.contributions;
+        const currentRouteGroupedDependencies = (currentContribution.dependencies ?? []).filter((dep) => isGroupedContentScriptAsset(dep));
+        const groupedDependencies = [...currentRouteGroupedDependencies];
+        const groupedAssetKeysByRoute = new Map();
+        const routeDisplayPaths = new Map();
+        const dependencyPaths = new Set([path.resolve(input.routeFile)]);
+        let hasCollectionFailures = groupedCollection.hasCollectionFailures;
+        if (currentRouteGroupedDependencies.length > 0) {
+            groupedAssetKeysByRoute.set(currentRouteLookupKey, new Set(currentRouteGroupedDependencies.map((dep) => getGroupedBundleAssetKey(dep.groupedBundle))));
+            routeDisplayPaths.set(currentRouteLookupKey, input.routeFile);
+        }
+        for (const groupedContribution of groupedContributions) {
+            if (groupedContribution.routeFile === input.routeFile &&
+                groupedContribution.dependencyInstanceKey === dependencyInstanceKey) {
+                continue;
+            }
+            const { contribution, routeFile } = groupedContribution;
+            if (!contribution?.dependencies?.length) {
+                continue;
+            }
+            const routeGroupedDependencies = contribution.dependencies.filter((dep) => isGroupedContentScriptAsset(dep));
+            if (routeGroupedDependencies.length === 0) {
+                continue;
+            }
+            groupedDependencies.push(...routeGroupedDependencies);
+            groupedAssetKeysByRoute.set(createRouteGraphLookupKey(routeFile, groupedContribution.dependencyInstanceKey), new Set(routeGroupedDependencies.map((dep) => getGroupedBundleAssetKey(dep.groupedBundle))));
+            routeDisplayPaths.set(createRouteGraphLookupKey(routeFile, groupedContribution.dependencyInstanceKey), routeFile);
+            dependencyPaths.add(path.resolve(routeFile));
+        }
+        if (groupedDependencies.length === 0) {
+            return {
+                assetsByRoute: new Map(),
+                dependencyPaths,
+                hasCollectionFailures,
+                cacheable: Boolean(input.groupedBuildPlan) && !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 = new Map();
+        const groupedAssetsByBundleKey = indexGroupedAssetsByBundleKey(processedGroupedDependencies);
+        for (const [routeFile, groupedAssetKeys] of groupedAssetKeysByRoute) {
+            const matchedAssets = [...groupedAssetKeys]
+                .flatMap((assetKey) => groupedAssetsByBundleKey.get(assetKey) ?? [])
+                .sort((left, right) => left.index - right.index)
+                .map(({ asset }) => asset);
+            if (groupedAssetKeys.size > 0 && matchedAssets.length === 0) {
+                appLogger.warn(`Grouped page-browser assets for ${routeDisplayPaths.get(routeFile) ?? 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,
+            cacheable: Boolean(input.groupedBuildPlan) && !hasCollectionFailures,
+        };
+    }
+    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 };
+    }
+}

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/page-browser-graph/processed-asset-dedupe.js

@@ -0,0 +1,23 @@
+export function buildProcessedAssetDedupeKey(asset) {
+    return [
+        asset.kind,
+        asset.position ?? '',
+        asset.srcUrl ?? '',
+        asset.filepath ?? '',
+        asset.content ?? '',
+        asset.inline ? 'inline' : 'external',
+        asset.excludeFromHtml ? 'excluded' : 'included',
+        asset.packageRole ?? '',
+        JSON.stringify(asset.attributes ?? {}),
+    ].join('|');
+}
+export function dedupeProcessedAssets(assets) {
+    const unique = new Map();
+    for (const asset of assets) {
+        const key = buildProcessedAssetDedupeKey(asset);
+        if (!unique.has(key)) {
+            unique.set(key, asset);
+        }
+    }
+    return [...unique.values()];
+}

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

@@ -0,0 +1,38 @@
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+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.
+ */
+export type IntegrationRouteRenderAdapterHost<C> = {
+    readonly name: string;
+    readonly appConfig: EcoPagesAppConfig;
+    readonly watch: boolean;
+    readonly hostOwnsDevClient?: boolean;
+    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>;
+    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: {
+        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,26 @@
+import { buildRouteHtmlFinalization } from './route-html-finalization.service.js';
+/**
+ * Builds the internal route-render adapter consumed by `RouteRenderOrchestrator`.
+ */
+export function createIntegrationRouteRenderAdapter(host) {
+    return {
+        name: host.name,
+        resolveRouteRenderInputs: (routeOptions) => host.resolveRouteRenderInputs(routeOptions),
+        resolveRouteDependencies: (input) => host.resolveRouteDependencies(input),
+        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,
+            watch: host.watch,
+            hostOwnsDevClient: host.hostOwnsDevClient,
+            integrationName: host.name,
+            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),
+    };
+}

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,25 @@
+export function decodeHtmlEntities(value) {
+    let decoded = value;
+    let previous;
+    do {
+        previous = decoded;
+        decoded = decoded
+            .replaceAll('"', '"')
+            .replaceAll(''', "'")
+            .replaceAll(''', "'")
+            .replaceAll('&lt;', '<')
+            .replaceAll('&gt;', '>')
+            .replaceAll('&amp;', '&');
+    } while (decoded !== previous);
+    return decoded;
+}
+export 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));
+}
+export function inspectUnresolvedMarkerArtifactHtml(html) {
+    const normalizedHtml = normalizeUnresolvedMarkerArtifactHtml(html);
+    return {
+        normalizedHtml,
+        hasUnresolvedMarkerArtifacts: normalizedHtml.includes('<eco-marker'),
+    };
+}

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,43 @@
+import { escapeHtmlAttribute } from '../../../utils/html-escaping.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 function buildRobotsMetaContribution(metadata) {
+    const content = formatRobotsMetaContent(metadata.robots);
+    if (!content) {
+        return undefined;
+    }
+    return {
+        placement: 'head-append',
+        html: `<meta name="robots" content="${escapeHtmlAttribute(content)}">`,
+    };
+}
+/**
+ * Formats robots directives for a meta tag, or `undefined` when defaults apply.
+ */
+export function formatRobotsMetaContent(robots) {
+    if (!robots) {
+        return undefined;
+    }
+    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 undefined;
+    }
+    return directives.join(', ');
+}

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

@@ -0,0 +1,25 @@
+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';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+export type RouteHtmlFinalizationContext<C> = {
+    appConfig: EcoPagesAppConfig;
+    watch: boolean;
+    hostOwnsDevClient?: boolean;
+    integrationName: string;
+    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,44 @@
+import { buildRobotsMetaContribution } from './robots-meta.contribution.js';
+import { DevToolbarHost } from '../../../dev-toolbar/dev-toolbar-host.js';
+/**
+ * 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 function buildRouteHtmlFinalization(context) {
+    const { renderOptions } = context;
+    const documentAttributes = context.getDocumentAttributes(renderOptions);
+    const integrationContributions = context.getHtmlDocumentContributions({ renderOptions, partial: false }) ?? [];
+    const robotsContribution = buildRobotsMetaContribution(renderOptions.metadata ?? {});
+    const devToolbarContribution = buildDevToolbarManifestContribution(context);
+    const htmlContributions = [
+        ...(robotsContribution ? [robotsContribution] : []),
+        ...(devToolbarContribution ? [devToolbarContribution] : []),
+        ...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);
+        },
+    };
+}
+function buildDevToolbarManifestContribution(context) {
+    return DevToolbarHost.forApp(context.appConfig, {
+        watch: context.watch,
+        hostOwnsDevClient: context.hostOwnsDevClient,
+    }).buildRouteManifestContribution({
+        routeFile: context.renderOptions.file,
+        integrationName: context.integrationName,
+        pagePackage: context.renderOptions.pagePackage,
+    });
+}

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

@@ -0,0 +1,26 @@
+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;
+    resolvedPageDependencyComponents?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
+    resolvedDependencies: ProcessedAsset[];
+    allDependencies: ProcessedAsset[];
+    pageBrowserGraph?: PageBrowserGraphResult;
+    appConfig: EcoPagesAppConfig;
+}): IntegrationRendererRenderOptions<C>;
+export {};