@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

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

@@ -0,0 +1,171 @@
+import { buildInjectorMapScript } from "../../eco/lazy-injector-map.js";
+function cloneTemplateStrings(strings, firstString) {
+  const nextStrings = [...strings];
+  nextStrings[0] = firstString;
+  const rawDescriptor = Object.getOwnPropertyDescriptor(strings, "raw");
+  if (rawDescriptor && Array.isArray(rawDescriptor.value)) {
+    const rawStrings = [...rawDescriptor.value];
+    rawStrings[0] = firstString;
+    Object.defineProperty(nextStrings, "raw", {
+      ...rawDescriptor,
+      value: rawStrings
+    });
+  }
+  return nextStrings;
+}
+function cloneTemplateContentWithUpdatedFirstString(content, firstString) {
+  const descriptors = Object.getOwnPropertyDescriptors(content);
+  const clonedContent = Object.create(Object.getPrototypeOf(content));
+  const stringsDescriptor = descriptors.strings;
+  Object.defineProperties(clonedContent, {
+    ...descriptors,
+    strings: {
+      ...stringsDescriptor,
+      value: cloneTemplateStrings(content.strings, firstString)
+    }
+  });
+  return clonedContent;
+}
+function cloneMarkupNodeLikeWithUpdatedOuterHtml(content, outerHTML) {
+  const descriptors = Object.getOwnPropertyDescriptors(content);
+  const clonedContent = Object.create(Object.getPrototypeOf(content));
+  const outerHTMLDescriptor = descriptors.outerHTML;
+  Object.defineProperties(clonedContent, {
+    ...descriptors,
+    outerHTML: {
+      configurable: outerHTMLDescriptor?.configurable ?? true,
+      enumerable: outerHTMLDescriptor?.enumerable ?? true,
+      writable: true,
+      value: outerHTML
+    }
+  });
+  return clonedContent;
+}
+function wrapWithScriptsInjectorMarkup(content, injectorMapScript) {
+  return `<scripts-injector><script type="ecopages/injector-map">${injectorMapScript}<\/script>${content}<\/scripts-injector>`;
+}
+function cloneTemplateContentWithWrappedInjector(content, injectorMapScript) {
+  if (content.strings.length === 0) {
+    return wrapWithScriptsInjectorMarkup(String(content), injectorMapScript);
+  }
+  const nextStrings = [...content.strings];
+  nextStrings[0] = wrapWithScriptsInjectorMarkup(nextStrings[0] ?? "", injectorMapScript);
+  nextStrings[nextStrings.length - 1] = `${nextStrings[nextStrings.length - 1] ?? ""}<\/scripts-injector>`;
+  const rawDescriptor = Object.getOwnPropertyDescriptor(content.strings, "raw");
+  if (rawDescriptor && Array.isArray(rawDescriptor.value)) {
+    const rawStrings = [...rawDescriptor.value];
+    rawStrings[0] = wrapWithScriptsInjectorMarkup(rawStrings[0] ?? "", injectorMapScript);
+    rawStrings[rawStrings.length - 1] = `${rawStrings[rawStrings.length - 1] ?? ""}<\/scripts-injector>`;
+    Object.defineProperty(nextStrings, "raw", {
+      ...rawDescriptor,
+      value: rawStrings
+    });
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(content);
+  const clonedContent = Object.create(Object.getPrototypeOf(content));
+  const stringsDescriptor = descriptors.strings;
+  Object.defineProperties(clonedContent, {
+    ...descriptors,
+    strings: {
+      ...stringsDescriptor,
+      value: nextStrings
+    }
+  });
+  return clonedContent;
+}
+function isThenable(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function isTemplateContentShape(value) {
+  return typeof value === "object" && value !== null && Array.isArray(value.strings) && ((value.values ?? void 0) === void 0 || Array.isArray(value.values));
+}
+function isMarkupNodeLikeShape(value) {
+  return typeof value === "object" && value !== null && typeof value.nodeType === "number";
+}
+function injectTriggerAttributeIntoString(content, triggerId) {
+  const str = content;
+  let i = 0;
+  while (i < str.length) {
+    if (str[i] !== "<") {
+      i++;
+      continue;
+    }
+    const next = str[i + 1];
+    if (next === "!" || next === "?") {
+      const end = str.indexOf(">", i);
+      if (end === -1) break;
+      i = end + 1;
+      continue;
+    }
+    if (next && /[a-zA-Z]/.test(next)) {
+      const tagSlice = str.slice(i + 1);
+      const nameEnd = tagSlice.search(/[\s/>]/);
+      if (nameEnd === -1) break;
+      const insertAt = i + 1 + nameEnd;
+      return `${str.slice(0, insertAt)} data-eco-trigger="${triggerId}"${str.slice(insertAt)}`;
+    }
+    break;
+  }
+  return str;
+}
+function addTriggerAttribute(content, triggerId) {
+  if (isTemplateContentShape(content)) {
+    if (content.strings.length === 0) {
+      return String(content);
+    }
+    return cloneTemplateContentWithUpdatedFirstString(
+      content,
+      injectTriggerAttributeIntoString(content.strings[0] ?? "", triggerId)
+    );
+  }
+  if (isMarkupNodeLikeShape(content) && typeof content.outerHTML === "string") {
+    return cloneMarkupNodeLikeWithUpdatedOuterHtml(
+      content,
+      injectTriggerAttributeIntoString(content.outerHTML, triggerId)
+    );
+  }
+  return injectTriggerAttributeIntoString(String(content), triggerId);
+}
+function wrapWithScriptsInjector(content, lazyGroups) {
+  const injectorMapScript = buildInjectorMapScript(lazyGroups ?? []);
+  if (isTemplateContentShape(content)) {
+    return cloneTemplateContentWithWrappedInjector(content, injectorMapScript);
+  }
+  if (isMarkupNodeLikeShape(content) && typeof content.outerHTML === "string") {
+    return cloneMarkupNodeLikeWithUpdatedOuterHtml(
+      content,
+      wrapWithScriptsInjectorMarkup(content.outerHTML, injectorMapScript)
+    );
+  }
+  return wrapWithScriptsInjectorMarkup(String(content), injectorMapScript);
+}
+function decodeHtmlEntities(value) {
+  let decoded = value;
+  let previous;
+  do {
+    previous = decoded;
+    decoded = decoded.replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&#x27;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+  } while (decoded !== previous);
+  return decoded;
+}
+function normalizeUnresolvedMarkerArtifactHtml(html) {
+  return html.replace(
+    /&(?:amp;)?lt;eco-marker\b[\s\S]*?&(?:amp;)?gt;&(?:amp;)?lt;\/eco-marker&(?:amp;)?gt;/g,
+    (marker) => decodeHtmlEntities(marker)
+  );
+}
+function inspectUnresolvedMarkerArtifactHtml(html) {
+  const normalizedHtml = normalizeUnresolvedMarkerArtifactHtml(html);
+  return {
+    normalizedHtml,
+    hasUnresolvedMarkerArtifacts: normalizedHtml.includes("<eco-marker")
+  };
+}
+export {
+  addTriggerAttribute,
+  decodeHtmlEntities,
+  inspectUnresolvedMarkerArtifactHtml,
+  isThenable,
+  normalizeUnresolvedMarkerArtifactHtml,
+  wrapWithScriptsInjector
+};

package/src/route-renderer/orchestration/route-render-orchestrator.d.ts

@@ -0,0 +1,156 @@
+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';
+export type RouteRenderOrchestratorResolvedInputs = {
+    Page: EcoPageFile['default'] | EcoPageComponent<any>;
+    HtmlTemplate: EcoComponent<HtmlTemplateProps>;
+    Layout?: EcoComponent;
+    props: Record<string, unknown>;
+    metadata: PageMetadataProps;
+    integrationSpecificProps: Record<string, unknown>;
+};
+export type RouteRenderOrchestratorResolvedDependencies = {
+    resolvedDependencies: ProcessedAsset[];
+};
+/**
+ * Structural HTML work applied after the route body has been fully resolved.
+ *
+ * The shared route flow only needs to know whether a post-render HTML step
+ * exists. When `finalizeHtml` is absent, the captured body can be reused as-is.
+ */
+export type RouteHtmlFinalization = {
+    finalizeHtml?(html: string): string;
+    htmlContributions?: HtmlDocumentContribution[];
+};
+export interface RouteRenderOrchestratorAdapter<C> {
+    /**
+     * Name of the owning Integration for the current route render.
+     */
+    readonly name: string;
+    /**
+     * Loads the Integration-owned route inputs needed for one Page render.
+     */
+    resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
+    /**
+     * Resolves route-owned dependencies needed before Integration rendering starts.
+     */
+    resolveRouteDependencies(input: {
+        components: (EcoComponent | Partial<EcoComponent>)[];
+    }): Promise<RouteRenderOrchestratorResolvedDependencies>;
+    /**
+     * Collects declarative Page Browser Graph requirements for one route.
+     */
+    collectPageBrowserGraphContribution(routeFile: string): Promise<PageBrowserGraphContribution | undefined>;
+    /**
+     * Resolves the optional page-root render through the foreign-child-aware component contract.
+     */
+    resolveRoutePageComponentRender(input: {
+        Page: EcoComponent;
+        Layout?: EcoComponent;
+        props: Record<string, unknown>;
+        routeOptions: RouteRendererOptions;
+    }): Promise<ComponentRenderResult | undefined>;
+    /**
+     * Executes the Integration-specific route render.
+     */
+    renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    /**
+     * Returns the structural Html finalization plan for one prepared route render.
+     */
+    getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization;
+    /**
+     * Runs SSR-policy response transformation and returns the body value exposed to callers.
+     */
+    transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
+}
+/**
+ * Captured route-render output in both replayable body and string HTML forms.
+ */
+export interface CapturedHtmlRenderResult {
+    body: RouteRendererBody;
+    html: string;
+}
+/**
+ * Optional app-scoped collaborators used by the route render orchestrator.
+ */
+export interface RouteRenderOrchestratorDependencies {
+    ownershipPlanningService?: OwnershipPlanningService;
+    ownershipValidationService?: OwnershipValidationService;
+}
+/**
+ * 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 declare class RouteRenderOrchestrator {
+    private readonly appConfig;
+    private readonly assetProcessingService;
+    private readonly ownershipPlanningService;
+    private readonly ownershipValidationService;
+    private readonly pageBrowserGraphCache;
+    private readonly groupedPageBrowserGraphCache;
+    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.
+     */
+    prepareRenderOptions<C = unknown>(routeOptions: RouteRendererOptions, adapter: RouteRenderOrchestratorAdapter<C>): Promise<IntegrationRendererRenderOptions<C>>;
+    resolveDeclaredPageBrowserGraph(input: {
+        routeFile: string;
+        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.
+     */
+    captureHtmlRender(render: () => Promise<RouteRendererBody>): Promise<CapturedHtmlRenderResult>;
+    /**
+     * Executes the full route-render flow and returns the final body plus cache strategy.
+     */
+    execute<C = unknown>(options: RouteRendererOptions, adapter: RouteRenderOrchestratorAdapter<C>): Promise<RouteRenderResult>;
+    /**
+     * Executes the route-render finalization path for already prepared render options.
+     */
+    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;
+}