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

package/src/route-renderer/orchestration/integration-renderer.test-fixtures.d.ts

@@ -0,0 +1,75 @@
+import { IntegrationRenderer, type HtmlDocumentContribution, type RenderToResponseContext } from './integration-renderer.js';
+import { getComponentRenderContext, type ForeignChildRuntime } from './foreign-child/component-render-context.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { AssetProcessingService, ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoPagesElement, IntegrationRendererRenderOptions, EcoPageFile, RouteRendererBody, RouteRendererOptions, EcoComponent, HtmlTemplateProps } from '../../types/public-types.js';
+import type { PagePackageResult } from '../../types/public-types.js';
+export declare function createUnresolvedMarkerArtifact(nodeId: string, componentRef: string, propsRef: string): string;
+export declare function createMockIntegrationPlugin(plugin: {
+    name: string;
+} & Record<string, unknown>): EcoPagesAppConfig['integrations'][number];
+export declare const testAppConfig: EcoPagesAppConfig;
+export declare const testAssetService: AssetProcessingService;
+/**
+ * Concrete implementation with ed file loading for testing purposes.
+ */
+export declare class TestIntegrationRenderer extends IntegrationRenderer<EcoPagesElement> {
+    name: string;
+    ForeignChildRuntimeCreationCount: number;
+    ForeignChildRenderCount: number;
+    UseFailFastForeignChildRuntime: boolean;
+    PageModule: EcoPageFile | null;
+    HtmlTemplate: EcoComponent<HtmlTemplateProps> | null;
+    RenderedBody: RouteRendererBody;
+    RenderBodyFactory: ((context: ReturnType<typeof getComponentRenderContext>) => RouteRendererBody | Promise<RouteRendererBody>) | null;
+    MockComponentRenderResult: ComponentRenderResult | null;
+    ImportedFiles: string[];
+    HtmlContributions: HtmlDocumentContribution[];
+    render(_options: IntegrationRendererRenderOptions<EcoPagesElement>): Promise<RouteRendererBody>;
+    renderComponent(_input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    renderToResponse<P>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
+    protected importPageFile(_file: string): Promise<EcoPageFile>;
+    protected getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
+    protected resolveDependencies(_components: (EcoComponent | Partial<EcoComponent>)[]): Promise<ProcessedAsset[]>;
+    testPrepareRenderOptions(options: RouteRendererOptions): Promise<IntegrationRendererRenderOptions<EcoPagesElement>>;
+    testShouldDelegateForeignChild(input: {
+        currentIntegration: string;
+        targetIntegration?: string;
+    }): boolean;
+    testHasForeignChildDescendants(component: EcoComponent): boolean;
+    testGetHtmlTemplate(): Promise<import("../../index.browser.js").EcoFunctionComponent<HtmlTemplateProps<EcoPagesElement>, any>>;
+    testBaseGetHtmlTemplate(): Promise<import("../../index.browser.js").EcoFunctionComponent<HtmlTemplateProps<EcoPagesElement>, any>>;
+    testGetRendererBootstrapDependencies(partial?: boolean): ProcessedAsset[];
+    testFinalizeDocumentShellHtml(options: {
+        html: string;
+        partial?: boolean;
+        htmlContributions?: HtmlDocumentContribution[];
+    }): Promise<string>;
+    testTransformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<RouteRendererBody>;
+    appendTestProcessedDependencies(assets: ProcessedAsset[]): ProcessedAsset[];
+    setTestPagePackage(pagePackage: PagePackageResult): void;
+    getTestPagePackage(): PagePackageResult | undefined;
+    getTestProcessedDependencies(): ProcessedAsset[];
+    testRenderPartialViewResponse<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx?: RenderToResponseContext;
+        renderInline?: () => Promise<BodyInit>;
+        transformHtml?: (html: string) => string;
+    }): Promise<Response>;
+    testRenderViewWithDocumentShell<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx?: RenderToResponseContext;
+        layout?: EcoComponent;
+    }): Promise<Response>;
+    testRenderForeignSubtree(input: ComponentRenderInput): Promise<import("../../index.browser.js").ForeignSubtreeRenderPayload>;
+    protected createForeignChildRuntime(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): ForeignChildRuntime;
+    protected getHtmlDocumentContributions(_options?: {
+        partial?: boolean;
+    }): HtmlDocumentContribution[] | undefined;
+}

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

@@ -0,0 +1,173 @@
+import { vi } from 'vitest';
+import { resolveInnermostPageLayout } from './document-shell/layout-shell-props.service.js';
+import { finalizeDocumentShellHtml } from './document-shell/document-shell-render.service.js';
+import { IntegrationRenderer, } from './integration-renderer.js';
+import { getComponentRenderContext } from './foreign-child/component-render-context.js';
+import { toForeignSubtreeRenderPayload } from './foreign-child/foreign-subtree-execution.service.js';
+export function createUnresolvedMarkerArtifact(nodeId, componentRef, propsRef) {
+    return `<eco-marker data-eco-node-id="${nodeId}" data-eco-component-ref="${componentRef}" data-eco-props-ref="${propsRef}"></eco-marker>`;
+}
+export function createMockIntegrationPlugin(plugin) {
+    return {
+        setConfig: vi.fn(),
+        setRuntimeOrigin: vi.fn(),
+        setup: vi.fn(async () => { }),
+        ...plugin,
+    };
+}
+export const testAppConfig = {
+    absolutePaths: {
+        pagesDir: '/app/pages',
+        htmlTemplatePath: '/app/index.ts',
+    },
+    integrations: [],
+    defaultMetadata: {
+        title: 'Default Title',
+        description: 'Default Description',
+    },
+    srcDir: '/app',
+};
+export const testAssetService = {
+    processDependencies: vi.fn(() => Promise.resolve([])),
+};
+/**
+ * Concrete implementation with ed file loading for testing purposes.
+ */
+export class TestIntegrationRenderer extends IntegrationRenderer {
+    name = 'test-renderer';
+    ForeignChildRuntimeCreationCount = 0;
+    ForeignChildRenderCount = 0;
+    UseFailFastForeignChildRuntime = false;
+    PageModule = null;
+    HtmlTemplate = null;
+    RenderedBody = '<html><body>Test Page</body></html>';
+    RenderBodyFactory = null;
+    MockComponentRenderResult = null;
+    ImportedFiles = [];
+    HtmlContributions = [];
+    async render(_options) {
+        if (this.RenderBodyFactory) {
+            return await this.RenderBodyFactory(getComponentRenderContext());
+        }
+        return this.RenderedBody;
+    }
+    async renderComponent(_input) {
+        if (this.MockComponentRenderResult) {
+            return this.MockComponentRenderResult;
+        }
+        return super.renderComponent(_input);
+    }
+    async renderComponentWithForeignChildren(input) {
+        this.ForeignChildRenderCount += 1;
+        return await super.renderComponentWithForeignChildren(input);
+    }
+    async renderToResponse(view, props, ctx) {
+        const viewFn = view;
+        const content = viewFn(props);
+        let body;
+        if (ctx.partial) {
+            body = content;
+        }
+        else {
+            const Layout = resolveInnermostPageLayout(view.config?.layouts);
+            const children = Layout ? Layout({ children: content }) : content;
+            body = `<!DOCTYPE html><html><body>${children}</body></html>`;
+        }
+        const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8' });
+        if (ctx.headers) {
+            for (const [key, value] of Object.entries(ctx.headers)) {
+                headers.set(key, value);
+            }
+        }
+        return new Response(body, {
+            status: ctx.status ?? 200,
+            headers,
+        });
+    }
+    async importPageFile(_file) {
+        this.ImportedFiles.push(_file);
+        if (!this.PageModule)
+            throw new Error('Mock page module not set');
+        return this.PageModule;
+    }
+    async getHtmlTemplate() {
+        if (!this.HtmlTemplate)
+            throw new Error('Mock HTML template not set');
+        return this.HtmlTemplate;
+    }
+    async resolveDependencies(_components) {
+        return [];
+    }
+    async testPrepareRenderOptions(options) {
+        return this.prepareRenderOptions(options);
+    }
+    testShouldDelegateForeignChild(input) {
+        return this.foreignSubtreeExecutionService.shouldDelegateForeignChild(input);
+    }
+    testHasForeignChildDescendants(component) {
+        return this.hasForeignChildDescendants(component);
+    }
+    async testGetHtmlTemplate() {
+        return this.getHtmlTemplate();
+    }
+    async testBaseGetHtmlTemplate() {
+        return super.getHtmlTemplate();
+    }
+    testGetRendererBootstrapDependencies(partial = false) {
+        return this.getRendererBootstrapDependencies(partial);
+    }
+    async testFinalizeDocumentShellHtml(options) {
+        this.appendProcessedDependencies(this.getRendererBootstrapDependencies(options.partial));
+        return finalizeDocumentShellHtml(this.htmlTransformer, {
+            html: options.html,
+            partial: options.partial,
+            htmlContributions: options.htmlContributions ?? this.getHtmlDocumentContributions({ partial: options.partial ?? false }),
+        });
+    }
+    async testTransformRouteResponse(response, htmlContributions, pagePackage) {
+        const adapter = this.createRouteRenderOrchestratorAdapter();
+        return adapter.transformRouteResponse(response, htmlContributions, pagePackage);
+    }
+    appendTestProcessedDependencies(assets) {
+        return this.appendProcessedDependencies(assets);
+    }
+    setTestPagePackage(pagePackage) {
+        this.htmlTransformer.setPagePackage(pagePackage);
+    }
+    getTestPagePackage() {
+        return this.htmlTransformer.getPagePackage();
+    }
+    getTestProcessedDependencies() {
+        return this.htmlTransformer.getProcessedDependencies();
+    }
+    async testRenderPartialViewResponse(input) {
+        return this.renderPartialViewResponse({
+            view: input.view,
+            props: input.props,
+            ctx: input.ctx ?? { partial: true },
+            renderInline: input.renderInline,
+            transformHtml: input.transformHtml,
+        });
+    }
+    async testRenderViewWithDocumentShell(input) {
+        return this.renderViewWithDocumentShell({
+            view: input.view,
+            props: input.props,
+            ctx: input.ctx ?? {},
+            layout: input.layout,
+        });
+    }
+    async testRenderForeignSubtree(input) {
+        return toForeignSubtreeRenderPayload(await this.renderComponentWithForeignChildren(input));
+    }
+    createForeignChildRuntime(options) {
+        this.ForeignChildRuntimeCreationCount += 1;
+        if (this.UseFailFastForeignChildRuntime) {
+            return this.createFailFastForeignChildRuntime();
+        }
+        return super.createForeignChildRuntime(options);
+    }
+    getHtmlDocumentContributions(_options) {
+        return this.HtmlContributions;
+    }
+}

package/src/route-renderer/orchestration/ownership-graph/component-graph-collectors.d.ts

@@ -0,0 +1,10 @@
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { EcoComponent, ResolvedLazyTrigger } from '../../../types/public-types.js';
+import type { AssetDefinition } from '../../../services/assets/asset-processing-service/index.js';
+import type { AssetProcessingService, ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+export declare function collectIntegrationNamesFromGraph(components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): Set<string>;
+export declare function collectResolvedLazyTriggersFromGraph(components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): ResolvedLazyTrigger[];
+export declare function hasForeignChildDescendantsInGraph(component: EcoComponent, currentIntegrationName: string): boolean;
+export declare function collectEagerSsrLazyScriptDefinitions(components: (EcoComponent | Partial<EcoComponent>)[]): AssetDefinition[];
+export declare function collectUsedIntegrationDependenciesFromGraph(appConfig: EcoPagesAppConfig, components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): ProcessedAsset[];
+export declare function buildEagerSsrLazyAssetsFromGraph(assetProcessingService: AssetProcessingService, components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): Promise<ProcessedAsset[]>;

package/src/route-renderer/orchestration/ownership-graph/component-graph-collectors.js

@@ -0,0 +1,132 @@
+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 }));
+}
+export function collectIntegrationNamesFromGraph(components, currentIntegrationName) {
+    const integrationNames = new Set();
+    walkComponentGraph({
+        roots: toGraphRoots(components),
+        currentIntegrationName,
+        onComponent: ({ component }) => {
+            const integrationName = getComponentIdentity(component)?.integration ?? component.config?.integration;
+            if (integrationName) {
+                integrationNames.add(integrationName);
+            }
+        },
+    });
+    return integrationNames;
+}
+export function collectResolvedLazyTriggersFromGraph(components, currentIntegrationName) {
+    const triggers = [];
+    walkComponentGraph({
+        roots: toGraphRoots(components),
+        currentIntegrationName,
+        onComponent: ({ component }) => {
+            const ownTriggers = component.config?._resolvedLazyTriggers;
+            if (ownTriggers?.length) {
+                triggers.push(...ownTriggers);
+            }
+        },
+    });
+    return triggers;
+}
+export function hasForeignChildDescendantsInGraph(component, currentIntegrationName) {
+    let foundForeign = false;
+    walkComponentGraph({
+        roots: [{ component }],
+        currentIntegrationName,
+        onComponent: ({ component: currentComponent }) => {
+            if (foundForeign) {
+                return false;
+            }
+            const integrationName = getComponentIdentity(currentComponent)?.integration ?? currentComponent.config?.integration;
+            if (integrationName && integrationName !== currentIntegrationName) {
+                foundForeign = true;
+                return false;
+            }
+        },
+    });
+    return foundForeign;
+}
+export function collectEagerSsrLazyScriptDefinitions(components) {
+    const dependencies = [];
+    const seenKeys = new Set();
+    const normalizeAttributes = (attributes) => ({
+        type: 'module',
+        defer: '',
+        ...(attributes ?? {}),
+    });
+    walkComponentGraph({
+        roots: toGraphRoots(components),
+        currentIntegrationName: '',
+        visitLayout: true,
+        onConfig: (config) => {
+            const componentFile = getComponentIdentity(config)?.file;
+            if (!componentFile || !config) {
+                return;
+            }
+            const componentDir = path.dirname(componentFile);
+            for (const script of config.dependencies?.scripts ?? []) {
+                if (typeof script === 'string' || !script.lazy || script.ssr !== true) {
+                    continue;
+                }
+                const attributes = normalizeAttributes(script.attributes);
+                if (script.content) {
+                    const key = `content:${script.content}:${JSON.stringify(attributes)}`;
+                    if (seenKeys.has(key)) {
+                        continue;
+                    }
+                    seenKeys.add(key);
+                    dependencies.push(AssetFactory.createContentScript({
+                        position: 'head',
+                        content: script.content,
+                        attributes,
+                        packageRole: 'dynamic-chunk',
+                    }));
+                    continue;
+                }
+                if (!script.src) {
+                    continue;
+                }
+                const resolvedPath = path.resolve(componentDir, script.src);
+                const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
+                if (seenKeys.has(key)) {
+                    continue;
+                }
+                seenKeys.add(key);
+                dependencies.push(AssetFactory.createFileScript({
+                    filepath: resolvedPath,
+                    position: 'head',
+                    attributes,
+                    packageRole: 'dynamic-chunk',
+                }));
+            }
+        },
+    });
+    return dependencies;
+}
+export function collectUsedIntegrationDependenciesFromGraph(appConfig, components, currentIntegrationName) {
+    const integrationNames = collectIntegrationNamesFromGraph(components, currentIntegrationName);
+    const dependencies = [];
+    for (const integrationName of integrationNames) {
+        if (integrationName === currentIntegrationName) {
+            continue;
+        }
+        const integrationPlugin = appConfig.integrations.find((integration) => integration.name === integrationName);
+        if (!integrationPlugin || typeof integrationPlugin.getResolvedIntegrationDependencies !== 'function') {
+            continue;
+        }
+        dependencies.push(...integrationPlugin.getResolvedIntegrationDependencies());
+    }
+    return dependencies;
+}
+export async function buildEagerSsrLazyAssetsFromGraph(assetProcessingService, components, currentIntegrationName) {
+    const dependencies = collectEagerSsrLazyScriptDefinitions(components);
+    if (dependencies.length === 0) {
+        return [];
+    }
+    return assetProcessingService.processDependencies(dependencies, `${currentIntegrationName}:ssr-lazy`);
+}

package/src/route-renderer/orchestration/ownership-graph/component-graph.d.ts

@@ -0,0 +1,34 @@
+import type { EcoComponent, OwnershipPlanNodeSource } from '../../../types/public-types.js';
+export type DeclaredOwnershipRoot = {
+    component: EcoComponent;
+    source: Extract<OwnershipPlanNodeSource, 'page' | 'layout' | 'html-template'>;
+};
+export type DeclaredOwnershipNodeInput = {
+    component: EcoComponent;
+    source: Exclude<OwnershipPlanNodeSource, 'route'>;
+    parentIntegrationName: string;
+    integrationName: string;
+    componentId: string;
+    isForeignToParent: boolean;
+};
+export type ComponentGraphRoot = {
+    component: EcoComponent | Partial<EcoComponent>;
+    source?: Exclude<OwnershipPlanNodeSource, 'route'>;
+};
+export type ComponentGraphWalkInput = {
+    component: EcoComponent;
+    parentIntegrationName: string;
+    source?: Exclude<OwnershipPlanNodeSource, 'route'>;
+};
+export declare function walkComponentGraph(input: {
+    roots: ComponentGraphRoot[];
+    currentIntegrationName: string;
+    visitLayout?: boolean;
+    onComponent?: (node: ComponentGraphWalkInput) => void | boolean;
+    onConfig?: (config: EcoComponent['config']) => void;
+}): void;
+export declare function mapComponentGraph<T>(input: {
+    roots: DeclaredOwnershipRoot[];
+    currentIntegrationName: string;
+    mapNode: (node: DeclaredOwnershipNodeInput, children: T[]) => T;
+}): T[];

package/src/route-renderer/orchestration/ownership-graph/component-graph.js

@@ -0,0 +1,89 @@
+import { getComponentIdentity } from '../../../eco/component-identity.js';
+export function walkComponentGraph(input) {
+    const seenComponents = new Set();
+    const seenConfigs = new Set();
+    const visitComponent = (component, parentIntegrationName, source) => {
+        if (!component) {
+            return;
+        }
+        const ecoComponent = component;
+        if (seenComponents.has(ecoComponent)) {
+            return;
+        }
+        seenComponents.add(ecoComponent);
+        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);
+        }
+        if (input.onComponent) {
+            const shouldContinue = input.onComponent({
+                component: ecoComponent,
+                parentIntegrationName,
+                source,
+            });
+            if (shouldContinue === false) {
+                return;
+            }
+        }
+        if (input.visitLayout) {
+            for (const layout of ecoComponent.config?.layouts ?? []) {
+                if (layout?.config) {
+                    visitConfig(layout.config, integrationName);
+                }
+            }
+        }
+        for (const child of ecoComponent.config?.dependencies?.components ?? []) {
+            visitComponent(child, integrationName, 'dependency');
+        }
+    };
+    const visitConfig = (config, parentIntegrationName) => {
+        if (!config || seenConfigs.has(config)) {
+            return;
+        }
+        seenConfigs.add(config);
+        if (input.onConfig) {
+            input.onConfig(config);
+        }
+        if (input.visitLayout) {
+            for (const layout of config.layouts ?? []) {
+                if (layout?.config) {
+                    visitConfig(layout.config, parentIntegrationName);
+                }
+            }
+        }
+        for (const child of config.dependencies?.components ?? []) {
+            visitComponent(child, parentIntegrationName, 'dependency');
+        }
+    };
+    for (const root of input.roots) {
+        visitComponent(root.component, input.currentIntegrationName, root.source);
+    }
+}
+export function mapComponentGraph(input) {
+    let nextSyntheticId = 0;
+    const mapComponent = (component, source, parentIntegrationName, lineage) => {
+        const identity = getComponentIdentity(component);
+        const integrationName = component.config?.integration ?? identity?.integration ?? parentIntegrationName;
+        const isForeignToParent = integrationName !== parentIntegrationName;
+        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) => {
+            if (!child || nextLineage.has(child)) {
+                return [];
+            }
+            return [mapComponent(child, 'dependency', integrationName, nextLineage)];
+        });
+        return input.mapNode({
+            component,
+            source,
+            parentIntegrationName,
+            integrationName,
+            componentId,
+            isForeignToParent,
+        }, children);
+    };
+    return input.roots.map(({ component, source }) => mapComponent(component, source, input.currentIntegrationName, new Set()));
+}

package/src/route-renderer/orchestration/{ownership-validation.service.d.ts → ownership-graph/ownership-validation.service.d.ts}

@@ -1,5 +1,5 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { OwnershipPlanNodeSource, OwnershipValidationError, EcoComponent } from '../../types/public-types.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { OwnershipPlanNodeSource, OwnershipValidationError, EcoComponent } from '../../../types/public-types.js';
 type OwnershipValidationInput = {
     currentIntegrationName: string;
     roots: Array<{
@@ -26,4 +26,8 @@ export declare class OwnershipValidationService {
     validate(input: OwnershipValidationInput): OwnershipValidationError[];
     private isRegisteredIntegration;
 }
+/**
+ * Throws when declared ownership validation collected one or more errors.
+ */
+export declare function throwIfOwnershipInvalid(validationErrors: OwnershipValidationError[]): void;
 export {};

package/src/route-renderer/orchestration/ownership-graph/ownership-validation.service.js

@@ -0,0 +1,77 @@
+import { assertEcoDeclaredComponent } from '../../../eco/eco-declared-component.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.
+ *
+ * This check runs before route data and dependency preparation so ownership and
+ * metadata problems are surfaced from the loaded component graph itself rather
+ * than being entangled with ownership-plan construction.
+ */
+export class OwnershipValidationService {
+    appConfig;
+    /**
+     * Creates the ownership validator for one finalized app config.
+     */
+    constructor(appConfig) {
+        this.appConfig = appConfig;
+    }
+    /**
+     * Validates foreign ownership edges reachable from the supplied route roots.
+     */
+    validate(input) {
+        return mapComponentGraph({
+            roots: input.roots,
+            currentIntegrationName: input.currentIntegrationName,
+            mapNode: ({ component, integrationName, componentId, isForeignToParent }, children) => {
+                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;
+                }
+                if (integrationName === 'html') {
+                    return errors;
+                }
+                if (!componentMeta) {
+                    errors.push({
+                        code: 'MISSING_COMPONENT_METADATA',
+                        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,
+                    });
+                }
+                if (!this.isRegisteredIntegration(integrationName, input.currentIntegrationName)) {
+                    errors.push({
+                        code: 'UNKNOWN_INTEGRATION_OWNER',
+                        message: `[ecopages] Foreign child "${componentId}" references unknown integration owner "${integrationName}". Declared dependencies must include all possible foreign children and those integrations must be registered.`,
+                        componentId,
+                        componentFile: componentMeta?.file,
+                        integrationName,
+                    });
+                }
+                return errors;
+            },
+        }).flat();
+    }
+    isRegisteredIntegration(integrationName, currentIntegrationName) {
+        if (integrationName === currentIntegrationName) {
+            return true;
+        }
+        return this.appConfig.integrations.some((integration) => integration.name === integrationName);
+    }
+}
+/**
+ * Throws when declared ownership validation collected one or more errors.
+ */
+export function throwIfOwnershipInvalid(validationErrors) {
+    if (validationErrors.length === 0) {
+        return;
+    }
+    throw new Error(validationErrors.map((error) => error.message).join('\n'));
+}

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

@@ -0,0 +1,7 @@
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { ResolvedLazyTrigger } from '../../../types/public-types.js';
+import { type AssetProcessingService, type ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+/**
+ * Builds processed global-injector map and bootstrap assets for resolved lazy triggers.
+ */
+export declare function buildGlobalInjectorAssets(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService, triggers: ResolvedLazyTrigger[], currentIntegrationName: string): Promise<ProcessedAsset[]>;

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

@@ -0,0 +1,30 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { AssetFactory, } from '../../../services/assets/asset-processing-service/index.js';
+import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from '../../../eco/global-injector-map.js';
+/**
+ * Builds processed global-injector map and bootstrap assets for resolved lazy triggers.
+ */
+export async function buildGlobalInjectorAssets(appConfig, assetProcessingService, triggers, currentIntegrationName) {
+    const appProjectDir = appConfig.rootDir ?? appConfig.absolutePaths?.projectDir ?? process.cwd();
+    const appPackageRequire = createRequire(path.join(appProjectDir, 'package.json'));
+    const corePackageEntryPath = appPackageRequire.resolve('@ecopages/core');
+    const globalInjectorImportPath = createRequire(corePackageEntryPath).resolve('@ecopages/scripts-injector/global');
+    const mapScript = AssetFactory.createInlineContentScript({
+        position: 'head',
+        name: 'ecopages-global-injector-map',
+        content: buildGlobalInjectorMapScript(triggers),
+        attributes: { type: 'ecopages/global-injector-map' },
+        packageRole: 'keep-separate',
+        bundle: false,
+    });
+    const bootstrapInlineScript = AssetFactory.createInlineContentScript({
+        position: 'head',
+        name: 'ecopages-global-injector-bootstrap',
+        content: buildGlobalInjectorBootstrapContent(globalInjectorImportPath),
+        attributes: { type: 'module' },
+        packageRole: 'keep-separate',
+        bundle: true,
+    });
+    return assetProcessingService.processDependencies([mapScript, bootstrapInlineScript], currentIntegrationName);
+}

package/src/route-renderer/orchestration/page-browser-graph/grouped-graph-build-plan.d.ts

@@ -0,0 +1,15 @@
+import type { PageBrowserGraphContribution } from '../../../types/public-types.js';
+export type GroupedGraphBuildPlanInstance = {
+    routeFile: string;
+    dependencyInstanceKey: string;
+    contribution?: PageBrowserGraphContribution;
+};
+export type GroupedGraphBuildPlan = {
+    integrationName: string;
+    planKey: string;
+    instances: ReadonlyArray<GroupedGraphBuildPlanInstance>;
+};
+/**
+ * Builds a stable grouped-cache identity for one integration static export plan.
+ */
+export declare function createGroupedGraphBuildPlanKey(integrationName: string, instances: ReadonlyArray<Pick<GroupedGraphBuildPlanInstance, 'routeFile' | 'dependencyInstanceKey'>>): string;