@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.20

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

@@ -0,0 +1,25 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../types/public-types.js';
+import { type AssetProcessingService } from '../../services/assets/asset-processing-service/index.js';
+export type PageBrowserGraphResolveInput = {
+    routeFile: string;
+    integrationName: string;
+    collectContribution: (routeFile: string) => Promise<PageBrowserGraphContribution | undefined>;
+};
+/**
+ * Resolves declarative page browser graph assets for one route and integration.
+ */
+export declare class PageBrowserGraphService {
+    private readonly appConfig;
+    private readonly assetProcessingService;
+    private readonly pageBrowserGraphCache;
+    private readonly groupedPageBrowserGraphCache;
+    constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
+    resolvePageBrowserGraph(input: PageBrowserGraphResolveInput): Promise<PageBrowserGraphResult | undefined>;
+    private isHmrEnabled;
+    private buildPageBrowserGraph;
+    private resolveGroupedPageBrowserAssets;
+    private buildGroupedPageBrowserAssets;
+    private listIntegrationRouteFiles;
+    private partitionPageBrowserGraphAssets;
+}

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

@@ -0,0 +1,174 @@
+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";
+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;
+  pageBrowserGraphCache = /* @__PURE__ */ new Map();
+  groupedPageBrowserGraphCache = /* @__PURE__ */ new Map();
+  constructor(appConfig, assetProcessingService) {
+    this.appConfig = appConfig;
+    this.assetProcessingService = assetProcessingService;
+  }
+  async resolvePageBrowserGraph(input) {
+    if (this.isHmrEnabled()) {
+      return await this.buildPageBrowserGraph(input);
+    }
+    const cacheKey = `${input.integrationName}:${input.routeFile}`;
+    const cachedGraph = this.pageBrowserGraphCache.get(cacheKey);
+    if (cachedGraph) {
+      return await cachedGraph;
+    }
+    const pendingGraph = this.buildPageBrowserGraph(input).catch((error) => {
+      this.pageBrowserGraphCache.delete(cacheKey);
+      throw error;
+    });
+    this.pageBrowserGraphCache.set(cacheKey, pendingGraph);
+    return await pendingGraph;
+  }
+  isHmrEnabled() {
+    return typeof this.assetProcessingService.getHmrManager === "function" && this.assetProcessingService.getHmrManager()?.isEnabled() === true;
+  }
+  async buildPageBrowserGraph(input) {
+    const contribution = await input.collectContribution(input.routeFile);
+    if (!contribution) {
+      return void 0;
+    }
+    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)).get(input.routeFile) ?? [] : [];
+    const processedDependencies = ungroupedDependencies.length ? await this.assetProcessingService.processDependencies(
+      ungroupedDependencies,
+      `${input.integrationName}:${input.routeFile}`
+    ) : [];
+    const resolvedAssets = [...processedDependencies, ...groupedAssets, ...contribution.assets ?? []];
+    return this.partitionPageBrowserGraphAssets(resolvedAssets);
+  }
+  async resolveGroupedPageBrowserAssets(input, currentContribution) {
+    if (this.isHmrEnabled()) {
+      const result = await this.buildGroupedPageBrowserAssets(input, currentContribution);
+      return result.assetsByRoute;
+    }
+    const cacheKey = input.integrationName;
+    let pending = this.groupedPageBrowserGraphCache.get(cacheKey);
+    if (!pending) {
+      pending = this.buildGroupedPageBrowserAssets(input, currentContribution).then((result) => {
+        if (result.hasCollectionFailures) {
+          this.groupedPageBrowserGraphCache.delete(cacheKey);
+        }
+        return result.assetsByRoute;
+      }).catch((error) => {
+        this.groupedPageBrowserGraphCache.delete(cacheKey);
+        throw error;
+      });
+      this.groupedPageBrowserGraphCache.set(cacheKey, pending);
+    }
+    return await pending;
+  }
+  async buildGroupedPageBrowserAssets(input, currentContribution) {
+    const routeFiles = await this.listIntegrationRouteFiles(input.integrationName);
+    const currentRouteGroupedDependencies = (currentContribution.dependencies ?? []).filter(
+      (dep) => isGroupedContentScriptAsset(dep)
+    );
+    const groupedDependencies = [...currentRouteGroupedDependencies];
+    const groupedAssetKeysByRoute = /* @__PURE__ */ new Map();
+    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)))
+      );
+    }
+    if (groupedDependencies.length === 0) {
+      return {
+        assetsByRoute: /* @__PURE__ */ new Map(),
+        hasCollectionFailures
+      };
+    }
+    const processedGroupedDependencies = await this.assetProcessingService.processDependencies(
+      groupedDependencies,
+      `${input.integrationName}:grouped-page-browser-graph`
+    );
+    const groupedAssetsByRoute = /* @__PURE__ */ new Map();
+    for (const [routeFile, groupedAssetKeys] of groupedAssetKeysByRoute) {
+      groupedAssetsByRoute.set(
+        routeFile,
+        processedGroupedDependencies.filter((asset) => {
+          if (!asset.groupedBundle) {
+            return false;
+          }
+          return groupedAssetKeys.has(getGroupedBundleAssetKey(asset.groupedBundle));
+        })
+      );
+    }
+    return {
+      assetsByRoute: groupedAssetsByRoute,
+      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/render-output.utils.d.ts

@@ -21,6 +21,8 @@ type MarkupNodeLikeShape = {
  * @typeParam T Expected resolved type of the thenable.
  */
 export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;
+/** Returns whether a value looks like a DOM-like markup node from SSR integrations. */
+export declare function isMarkupNodeLike(value: unknown): value is MarkupNodeLikeShape;
 /**
  * Injects `data-eco-trigger` into the first real HTML element opening tag of
  * a component's rendered output string.

package/src/route-renderer/orchestration/render-output.utils.js

@@ -82,6 +82,9 @@ function isTemplateContentShape(value) {
 function isMarkupNodeLikeShape(value) {
   return typeof value === "object" && value !== null && typeof value.nodeType === "number";
 }
+function isMarkupNodeLike(value) {
+  return isMarkupNodeLikeShape(value);
+}
 function injectTriggerAttributeIntoString(content, triggerId) {
   const str = content;
   let i = 0;
@@ -165,6 +168,7 @@ export {
   addTriggerAttribute,
   decodeHtmlEntities,
   inspectUnresolvedMarkerArtifactHtml,
+  isMarkupNodeLike,
   isThenable,
   normalizeUnresolvedMarkerArtifactHtml,
   wrapWithScriptsInjector

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

@@ -0,0 +1,17 @@
+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;
+    applyAttributesToFirstBodyElement: (html: string, attributes: Record<string, string>) => string;
+    applyAttributesToHtmlElement: (html: string, attributes: Record<string, string>) => string;
+};
+/**
+ * Builds the structural HTML finalization plan for one prepared route render.
+ */
+export declare function buildRouteHtmlFinalization<C>(context: RouteHtmlFinalizationContext<C>): RouteHtmlFinalization;

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

@@ -0,0 +1,26 @@
+function buildRouteHtmlFinalization(context) {
+  const { renderOptions } = context;
+  const componentRootAttributes = renderOptions.componentRender?.canAttachAttributes && renderOptions.componentRender.rootAttributes && Object.keys(renderOptions.componentRender.rootAttributes).length > 0 ? renderOptions.componentRender.rootAttributes : void 0;
+  const documentAttributes = context.getDocumentAttributes(renderOptions);
+  const htmlContributions = context.getHtmlDocumentContributions({ renderOptions, partial: false });
+  const hasStructuralFinalization = componentRootAttributes && Object.keys(componentRootAttributes).length > 0 || documentAttributes && Object.keys(documentAttributes).length > 0;
+  if (!hasStructuralFinalization && (!htmlContributions || htmlContributions.length === 0)) {
+    return {};
+  }
+  return {
+    htmlContributions,
+    finalizeHtml: (html) => {
+      let renderedHtml = html;
+      if (componentRootAttributes) {
+        renderedHtml = context.applyAttributesToFirstBodyElement(renderedHtml, componentRootAttributes);
+      }
+      if (documentAttributes) {
+        renderedHtml = context.applyAttributesToHtmlElement(renderedHtml, documentAttributes);
+      }
+      return renderedHtml;
+    }
+  };
+}
+export {
+  buildRouteHtmlFinalization
+};

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

@@ -0,0 +1,26 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ComponentRenderResult, 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;
+    componentRender?: ComponentRenderResult;
+    appConfig: EcoPagesAppConfig;
+}): IntegrationRendererRenderOptions<C>;
+export {};

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

@@ -0,0 +1,54 @@
+import { createPagePackage } from "../../services/assets/asset-processing-service/index.js";
+import { dedupeProcessedAssets } from "./processed-asset-dedupe.js";
+import { createPageLocalsProxy } from "./route-prepared-options.utils.js";
+function buildPreparedRenderOptions(input) {
+  const {
+    routeOptions,
+    resolvedInputs,
+    resolvedDependencies,
+    allDependencies,
+    pageBrowserGraph,
+    componentRender,
+    appConfig
+  } = input;
+  const { Page, HtmlTemplate, Layouts, Layout, layoutEntries, props, metadata, integrationSpecificProps } = resolvedInputs;
+  const dedupedDependencies = dedupeProcessedAssets(allDependencies);
+  const pagePackage = createPagePackage(dedupedDependencies, { pageBrowserGraph });
+  const pageProps = {
+    ...props,
+    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,
+    componentRender,
+    HtmlTemplate,
+    Layouts,
+    Layout,
+    layoutEntries,
+    props,
+    Page,
+    metadata,
+    params: routeOptions.params || {},
+    query: routeOptions.query || {},
+    pageProps,
+    locals,
+    pageLocals,
+    cacheStrategy
+  };
+  return {
+    ...integrationSpecificProps,
+    ...preparedOptions
+  };
+}
+export {
+  buildPreparedRenderOptions
+};

package/src/route-renderer/orchestration/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-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

@@ -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 { ComponentRenderResult, 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-validation.service.js';
-import { OwnershipPlanningService } from './ownership-planning.service.js';
+import { PageBrowserGraphService } from './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>;
@@ -64,7 +66,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 +79,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,10 +93,8 @@ 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.
@@ -109,31 +109,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 +122,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;
 }