@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

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

@@ -0,0 +1,30 @@
+import { LocalsAccessError } from '../../../errors/locals-access-error.js';
+/**
+ * Proxy that throws when dynamic route locals are accessed on non-dynamic pages.
+ */
+export 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);
+        },
+    });
+}

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

@@ -1,13 +1,18 @@
-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, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult, EcoPageLayoutEntry } from '../../../types/public-types.js';
+import type { AssetProcessingService, ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import { OwnershipValidationService } from '../ownership-graph/ownership-validation.service.js';
+import { PageBrowserGraphService } from '../page-browser-graph/page-browser-graph.service.js';
+import type { GroupedGraphBuildPlan } from '../page-browser-graph/grouped-graph-build-plan.js';
+import type { ResolvedPageDependencies } from '../../page-loading/resolved-page-dependencies.js';
 export type RouteRenderOrchestratorResolvedInputs = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
+    pageModule: EcoPageFile;
     HtmlTemplate: EcoComponent<HtmlTemplateProps>;
+    Layouts: EcoComponent[];
     Layout?: EcoComponent;
+    layoutEntries?: EcoPageLayoutEntry[];
     props: Record<string, unknown>;
     metadata: PageMetadataProps;
     integrationSpecificProps: Record<string, unknown>;
@@ -41,18 +46,14 @@ export interface RouteRenderOrchestratorAdapter<C> {
         components: (EcoComponent | Partial<EcoComponent>)[];
     }): Promise<RouteRenderOrchestratorResolvedDependencies>;
     /**
-     * Collects declarative Page Browser Graph requirements for one route.
+     * Collects declarative Page Browser Graph requirements for one route instance.
      */
-    collectPageBrowserGraphContribution(routeFile: string): Promise<PageBrowserGraphContribution | undefined>;
+    collectPageBrowserGraphContribution(context: PageBrowserGraphContributionContext): Promise<PageBrowserGraphContribution | undefined>;
+    resolvePageDependencies(context: PageBrowserGraphContributionContext): Promise<ResolvedPageDependencies | undefined>;
     /**
-     * Resolves the optional page-root render through the foreign-child-aware component contract.
+     * Builds the graph contribution context for one route file and optional params.
      */
-    resolveRoutePageComponentRender(input: {
-        Page: EcoComponent;
-        Layout?: EcoComponent;
-        props: Record<string, unknown>;
-        routeOptions: RouteRendererOptions;
-    }): Promise<ComponentRenderResult | undefined>;
+    buildPageBrowserGraphContributionContext(routeFile: string, routeOptions?: Pick<RouteRendererOptions, 'params' | 'query'>): Promise<PageBrowserGraphContributionContext>;
     /**
      * Executes the Integration-specific route render.
      */
@@ -64,7 +65,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 +78,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,49 +92,24 @@ 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: {
         routeFile: string;
+        dependencyInstanceKey?: string;
         integrationName: string;
-        collectContribution: (routeFile: string) => Promise<PageBrowserGraphContribution | undefined>;
+        collectContribution: () => Promise<PageBrowserGraphContribution | undefined>;
+        groupedBuildPlan?: GroupedGraphBuildPlan;
     }): 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 +123,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;
 }

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

@@ -0,0 +1,215 @@
+import { collectHtmlCacheSourceDependencyPaths } from '../../../services/cache/html-page-cache-dependency-index.js';
+import { getComponentIdentity } from '../../../eco/component-identity.js';
+import { inspectUnresolvedMarkerArtifactHtml } from './marker-artifact.utils.js';
+import { OwnershipValidationService, throwIfOwnershipInvalid, } from '../ownership-graph/ownership-validation.service.js';
+import { buildEagerSsrLazyAssetsFromGraph, collectResolvedLazyTriggersFromGraph, collectUsedIntegrationDependenciesFromGraph, } from '../ownership-graph/component-graph-collectors.js';
+import { buildGlobalInjectorAssets } from '../page-browser-graph/global-injector-assets.service.js';
+import { mergePageBrowserGraphContributions } from '../page-browser-graph/page-browser-graph-contribution.merge.js';
+import { PageBrowserGraphService } from '../page-browser-graph/page-browser-graph.service.js';
+import { createPageDependencyInstanceKey } from '../page-browser-graph/route-instance-key.js';
+import { buildPreparedRenderOptions } from './route-prepared-options.builder.js';
+import { measureRouteRenderPhase } from '../../../diagnostics/request-pipeline-metrics.js';
+/**
+ * Owns one route render from normalized module loading through final HTML output.
+ *
+ * This orchestrator keeps route rendering as one app-scoped unit while still
+ * delegating integration-specific behavior through the adapter seam. It owns
+ * route-root validation, dependency aggregation, page package creation, and the
+ * final HTML/body handling that happens after the integration render returns.
+ */
+export class RouteRenderOrchestrator {
+    appConfig;
+    assetProcessingService;
+    ownershipValidationService;
+    pageBrowserGraphService;
+    constructor(appConfig, assetProcessingService, dependencies = {}) {
+        this.appConfig = appConfig;
+        this.assetProcessingService = assetProcessingService;
+        this.ownershipValidationService =
+            dependencies.ownershipValidationService ?? new OwnershipValidationService(appConfig);
+        this.pageBrowserGraphService =
+            dependencies.pageBrowserGraphService ?? new PageBrowserGraphService(appConfig, assetProcessingService);
+    }
+    /**
+     * Builds normalized route render options before the integration render runs.
+     *
+     * This preparation step validates route-root ownership, resolves page data,
+     * collects processed assets, and produces the page package consumed by downstream
+     * HTML transformation.
+     */
+    async prepareRenderOptions(routeOptions, adapter) {
+        const resolvedInputs = await measureRouteRenderPhase('resolve-route-inputs', () => adapter.resolveRouteRenderInputs(routeOptions));
+        const finalProps = {
+            ...resolvedInputs.props,
+            ...(routeOptions.props ?? {}),
+        };
+        const finalResolvedInputs = {
+            ...resolvedInputs,
+            props: finalProps,
+        };
+        const { Page, HtmlTemplate, Layouts } = finalResolvedInputs;
+        await measureRouteRenderPhase('ownership-validation', async () => {
+            const validationErrors = this.ownershipValidationService.validate({
+                currentIntegrationName: adapter.name,
+                roots: [
+                    { component: HtmlTemplate, source: 'html-template' },
+                    ...Layouts.map((layout) => ({ component: layout, source: 'layout' })),
+                    { component: Page, source: 'page' },
+                ],
+            });
+            throwIfOwnershipInvalid(validationErrors);
+        });
+        const componentsToResolve = [HtmlTemplate, ...Layouts, Page];
+        const dependencyInstanceKey = createPageDependencyInstanceKey({
+            params: routeOptions.params,
+            query: routeOptions.query,
+        });
+        const graphContext = {
+            file: routeOptions.file,
+            pageModule: finalResolvedInputs.pageModule,
+            props: finalProps,
+            params: routeOptions.params,
+            query: routeOptions.query,
+            dependencyInstanceKey,
+        };
+        const resolvedPageDependencies = await adapter.resolvePageDependencies(graphContext);
+        const { resolvedDependencies } = await measureRouteRenderPhase('resolve-dependencies', () => adapter.resolveRouteDependencies({
+            components: componentsToResolve,
+        }));
+        const pageBrowserGraph = await measureRouteRenderPhase('page-browser-graph', () => this.pageBrowserGraphService.resolvePageBrowserGraph({
+            routeFile: routeOptions.file,
+            dependencyInstanceKey,
+            integrationName: adapter.name,
+            collectContribution: async () => mergePageBrowserGraphContributions(await adapter.collectPageBrowserGraphContribution(graphContext), resolvedPageDependencies?.contribution),
+        }));
+        const graphDependencyPaths = this.pageBrowserGraphService.getDependencyPathsForRoute({
+            integrationName: adapter.name,
+            routeFile: routeOptions.file,
+            dependencyInstanceKey,
+        });
+        const resolvedPageDependencyComponents = resolvedPageDependencies?.components ?? [];
+        const allDependencies = [
+            ...resolvedDependencies,
+            ...collectUsedIntegrationDependenciesFromGraph(this.appConfig, componentsToResolve, adapter.name),
+        ];
+        const triggers = collectResolvedLazyTriggersFromGraph(componentsToResolve, adapter.name);
+        const [globalAssets, eagerSsrLazyAssets] = await Promise.all([
+            triggers.length > 0
+                ? buildGlobalInjectorAssets(this.appConfig, this.assetProcessingService, triggers, adapter.name)
+                : Promise.resolve([]),
+            buildEagerSsrLazyAssetsFromGraph(this.assetProcessingService, componentsToResolve, adapter.name),
+        ]);
+        allDependencies.push(...globalAssets, ...eagerSsrLazyAssets);
+        const sourceDependencyPaths = collectHtmlCacheSourceDependencyPaths({
+            routeFile: routeOptions.file,
+            processedAssets: allDependencies,
+            graphDependencyPaths,
+            additionalSourcePaths: collectRenderShellSourcePaths(this.appConfig, componentsToResolve),
+        });
+        return {
+            ...buildPreparedRenderOptions({
+                routeOptions,
+                resolvedInputs: finalResolvedInputs,
+                resolvedPageDependencyComponents,
+                resolvedDependencies,
+                allDependencies,
+                pageBrowserGraph,
+                appConfig: this.appConfig,
+            }),
+            sourceDependencyPaths,
+        };
+    }
+    async resolveDeclaredPageBrowserGraph(input) {
+        return await this.pageBrowserGraphService.resolvePageBrowserGraph(input);
+    }
+    /**
+     * Captures one route render body as HTML while preserving a replayable body value.
+     */
+    async captureHtmlRender(render) {
+        const renderedBody = await render();
+        const capturedRender = await this.captureRenderedBody(renderedBody);
+        return {
+            body: capturedRender.body,
+            html: capturedRender.html,
+        };
+    }
+    /**
+     * Executes the full route-render flow and returns the final body plus cache strategy.
+     */
+    async execute(options, adapter) {
+        const renderOptions = await this.prepareRenderOptions(options, adapter);
+        return this.executePrepared(renderOptions, adapter);
+    }
+    /**
+     * Executes the route-render finalization path for already prepared render options.
+     */
+    async executePrepared(renderOptions, adapter) {
+        const renderExecution = await measureRouteRenderPhase('render-body', () => this.captureHtmlRender(async () => adapter.renderRouteBody(renderOptions)));
+        const unresolvedArtifactInspection = inspectUnresolvedMarkerArtifactHtml(renderExecution.html);
+        const htmlFinalization = adapter.getRouteHtmlFinalization(renderOptions);
+        const hasUnresolvedMarkerHtml = unresolvedArtifactInspection.hasUnresolvedMarkerArtifacts;
+        if (hasUnresolvedMarkerHtml) {
+            throw new Error('[ecopages] Route render returned unresolved eco-marker artifact HTML. Full-route unresolved-marker fallback has been removed; resolve mixed foreign children inside renderComponentWithForeignChildren().');
+        }
+        const canReuseCapturedBody = !hasUnresolvedMarkerHtml && htmlFinalization.finalizeHtml === undefined;
+        if (canReuseCapturedBody) {
+            const responseBody = typeof renderExecution.body === 'string' ? renderExecution.body : renderExecution.html;
+            const body = await measureRouteRenderPhase('transform-response', () => adapter.transformRouteResponse(new Response(responseBody, {
+                headers: {
+                    'Content-Type': 'text/html',
+                },
+            }), htmlFinalization.htmlContributions, renderOptions.pagePackage));
+            return {
+                body,
+                cacheStrategy: renderOptions.cacheStrategy,
+                sourceDependencyPaths: renderOptions.sourceDependencyPaths,
+            };
+        }
+        const finalization = htmlFinalization.finalizeHtml
+            ? htmlFinalization.finalizeHtml(unresolvedArtifactInspection.normalizedHtml)
+            : unresolvedArtifactInspection.normalizedHtml;
+        const body = await measureRouteRenderPhase('transform-response', () => adapter.transformRouteResponse(new Response(finalization, {
+            headers: {
+                'Content-Type': 'text/html',
+            },
+        }), htmlFinalization.htmlContributions, renderOptions.pagePackage));
+        return {
+            body,
+            cacheStrategy: renderOptions.cacheStrategy,
+            sourceDependencyPaths: renderOptions.sourceDependencyPaths,
+        };
+    }
+    async captureRenderedBody(body) {
+        const response = new Response(body);
+        if (typeof body === 'string') {
+            return {
+                body,
+                html: await response.text(),
+            };
+        }
+        if (!response.body) {
+            return {
+                body,
+                html: await response.text(),
+            };
+        }
+        const [capturedBody, replayBody] = response.body.tee();
+        return {
+            body: replayBody,
+            html: await new Response(capturedBody).text(),
+        };
+    }
+}
+function collectRenderShellSourcePaths(appConfig, components) {
+    const sourcePaths = new Set();
+    if (appConfig.absolutePaths?.htmlTemplatePath) {
+        sourcePaths.add(appConfig.absolutePaths.htmlTemplatePath);
+    }
+    for (const component of components) {
+        const componentFile = getComponentIdentity(component)?.file;
+        if (componentFile) {
+            sourcePaths.add(componentFile);
+        }
+    }
+    return [...sourcePaths];
+}

package/src/route-renderer/orchestration/string-markup-renderer.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.js';
+import { IntegrationRenderer, type RenderToResponseContext } from './integration-renderer.js';
+/**
+ * Base renderer for integrations whose page output is string HTML markup.
+ *
+ * @remarks
+ * Ghtml, KitaJS, and MDX share the same document-shell rendering path. Subclasses
+ * only need to set `name` and override hooks for integration-specific behavior.
+ */
+export declare abstract class StringMarkupRenderer extends IntegrationRenderer<EcoPagesElement> {
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
+    renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
+}

package/src/route-renderer/orchestration/string-markup-renderer.js

@@ -0,0 +1,52 @@
+import { IntegrationRenderer } from './integration-renderer.js';
+import { resolveInnermostPageLayout } from './document-shell/layout-shell-props.service.js';
+/**
+ * Base renderer for integrations whose page output is string HTML markup.
+ *
+ * @remarks
+ * Ghtml, KitaJS, and MDX share the same document-shell rendering path. Subclasses
+ * only need to set `name` and override hooks for integration-specific behavior.
+ */
+export class StringMarkupRenderer extends IntegrationRenderer {
+    async renderComponent(input) {
+        if (typeof input.component !== 'function') {
+            throw new TypeError(`${this.name} renderer expected a callable component.`);
+        }
+        return this.renderStringComponentWithQueuedForeignSubtrees(input, input.component);
+    }
+    async render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, }) {
+        try {
+            return await this.renderPageWithDocumentShell({
+                page: {
+                    component: Page,
+                    props: { params, query, ...props, locals: pageLocals },
+                },
+                layout: Layout
+                    ? {
+                        component: Layout,
+                        props: locals ? { locals } : {},
+                    }
+                    : undefined,
+                htmlTemplate: HtmlTemplate,
+                metadata,
+                pageProps: pageProps ?? props ?? {},
+            });
+        }
+        catch (error) {
+            throw this.createRenderError('Error rendering page', error);
+        }
+    }
+    async renderToResponse(view, props, ctx) {
+        try {
+            return await this.renderViewWithDocumentShell({
+                view,
+                props,
+                ctx,
+                layout: resolveInnermostPageLayout(view.config?.layouts),
+            });
+        }
+        catch (error) {
+            throw this.createRenderError('Error rendering view', error);
+        }
+    }
+}