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

package/src/route-renderer/orchestration/foreign-subtree-execution.service.js

@@ -2,17 +2,18 @@ import {
   getComponentRenderContext,
   runWithComponentRenderContext
 } from "./component-render-context.js";
-import {
-  QueuedForeignSubtreeResolutionService
-} from "./queued-foreign-subtree-resolution.service.js";
-function isMarkupNodeLike(value) {
-  return typeof value === "object" && value !== null && "nodeType" in value && typeof value.nodeType === "number" && (!("outerHTML" in value) || typeof value.outerHTML === "string");
+import { isMarkupNodeLike } from "./render-output.utils.js";
+function toForeignSubtreeRenderPayload(result) {
+  return {
+    html: result.html,
+    assets: result.assets ?? [],
+    rootTag: result.rootTag,
+    rootAttributes: result.rootAttributes,
+    attachmentPolicy: result.canAttachAttributes ? { kind: "first-element" } : { kind: "none" },
+    integrationName: result.integrationName
+  };
 }
 class ForeignSubtreeExecutionService {
-  queuedForeignSubtreeResolutionService;
-  constructor(queuedForeignSubtreeResolutionService = new QueuedForeignSubtreeResolutionService()) {
-    this.queuedForeignSubtreeResolutionService = queuedForeignSubtreeResolutionService;
-  }
   requiresForeignChildRuntime(input) {
     const children = input.children ?? input.props.children;
     if (children === void 0 || children === null) {
@@ -26,18 +27,9 @@ class ForeignSubtreeExecutionService {
     }
     return !isMarkupNodeLike(children);
   }
-  /**
-   * Returns whether the current render pass must hand the child off to a foreign owner.
-   */
   shouldDelegateForeignChild(input) {
     return !!input.targetIntegration && input.targetIntegration !== input.currentIntegration;
   }
-  /**
-   * Creates the base runtime used when a renderer has not supplied its own queueing runtime.
-   *
-   * The runtime allows same-integration children to continue inline and fails fast
-   * when execution crosses into a foreign owner without a renderer-owned handoff.
-   */
   createFailFastRuntime(rendererName) {
     const interceptForeignChild = (input) => {
       if (!this.shouldDelegateForeignChild(input)) {
@@ -56,10 +48,10 @@ class ForeignSubtreeExecutionService {
     };
   }
   getQueuedRuntimeContext(input, runtimeContextKey) {
-    return this.queuedForeignSubtreeResolutionService.getRuntimeContext(input, runtimeContextKey);
+    return this.getRuntimeContext(input, runtimeContextKey);
   }
   createQueuedRuntime(options) {
-    return this.queuedForeignSubtreeResolutionService.createRuntime({
+    return this.createQueueRuntime({
       renderInput: options.renderInput,
       rendererCache: options.rendererCache,
       runtimeContextKey: options.runtimeContextKey,
@@ -68,9 +60,42 @@ class ForeignSubtreeExecutionService {
       createRuntimeContext: options.createRuntimeContext
     });
   }
-  /**
-   * Resolves a string-first renderer HTML fragment that may contain queued Foreign Subtree tokens.
-   */
+  createQueueRuntime(options) {
+    const runtimeContext = this.ensureRuntimeContext(options);
+    const interceptForeignChild = (input) => {
+      if (!options.shouldQueueForeignChild(input)) {
+        return {
+          kind: "inline",
+          props: { ...input.props }
+        };
+      }
+      runtimeContext.nextForeignSubtreeId += 1;
+      const foreignSubtreeId = runtimeContext.nextForeignSubtreeId;
+      const token = this.createForeignSubtreeToken(options.tokenPrefix, runtimeContext, foreignSubtreeId);
+      runtimeContext.queuedResolutions.push({
+        token,
+        component: input.component,
+        props: { ...input.props },
+        componentInstanceId: runtimeContext.componentInstanceScope ? `${runtimeContext.componentInstanceScope}_n_${foreignSubtreeId}` : `n_${foreignSubtreeId}`
+      });
+      return {
+        kind: "resolved",
+        value: token
+      };
+    };
+    return {
+      interceptForeignChild,
+      interceptForeignChildSync: interceptForeignChild
+    };
+  }
+  getRuntimeContext(input, runtimeContextKey) {
+    const integrationContext = input.integrationContext;
+    const runtimeContext = integrationContext?.[runtimeContextKey];
+    if (typeof runtimeContext !== "object" || runtimeContext === null) {
+      return void 0;
+    }
+    return runtimeContext;
+  }
   async resolveStringQueuedHtml(options) {
     const runtimeContext = this.getQueuedRuntimeContext(options.renderInput, options.runtimeContextKey);
     return this.resolveQueuedHtml({
@@ -98,7 +123,7 @@ class ForeignSubtreeExecutionService {
     });
   }
   async resolveQueuedHtml(options) {
-    return this.queuedForeignSubtreeResolutionService.resolveQueuedHtml({
+    return this.resolveQueuedForeignSubtreeTokens({
       html: options.html,
       runtimeContext: options.runtimeContext,
       queueLabel: options.queueLabel,
@@ -113,9 +138,93 @@ class ForeignSubtreeExecutionService {
       dedupeProcessedAssets: options.dedupeProcessedAssets
     });
   }
-  /**
-   * Executes one component render with Foreign Child support under the current integration.
-   */
+  async resolveQueuedForeignSubtreeTokens(options) {
+    if (!options.runtimeContext || options.runtimeContext.queuedResolutions.length === 0) {
+      return { assets: [], html: options.html };
+    }
+    const runtimeContext = options.runtimeContext;
+    const queuedResolutionsByToken = /* @__PURE__ */ new Map();
+    const resolvedHtmlByToken = /* @__PURE__ */ new Map();
+    const resolvingTokens = /* @__PURE__ */ new Set();
+    const collectedAssets = [];
+    const syncQueuedResolutions = () => {
+      for (const resolution of runtimeContext.queuedResolutions) {
+        if (!queuedResolutionsByToken.has(resolution.token)) {
+          queuedResolutionsByToken.set(resolution.token, resolution);
+        }
+      }
+    };
+    const resolveToken = async (token) => {
+      syncQueuedResolutions();
+      const cachedHtml = resolvedHtmlByToken.get(token);
+      if (cachedHtml) {
+        return cachedHtml;
+      }
+      const resolution = queuedResolutionsByToken.get(token);
+      if (!resolution) {
+        return token;
+      }
+      if (resolvingTokens.has(token)) {
+        throw new Error(
+          `[ecopages] ${options.queueLabel} foreign-subtree queue contains a cycle or unresolved dependency links.`
+        );
+      }
+      resolvingTokens.add(token);
+      try {
+        const renderedChildren = await options.renderQueuedChildren(
+          resolution.props.children,
+          runtimeContext,
+          queuedResolutionsByToken,
+          resolveToken
+        );
+        syncQueuedResolutions();
+        if (renderedChildren.assets.length > 0) {
+          collectedAssets.push(...renderedChildren.assets);
+        }
+        const foreignSubtreeRender = await options.resolveForeignSubtree(
+          {
+            component: resolution.component,
+            props: { ...resolution.props },
+            children: renderedChildren.html ?? renderedChildren.children,
+            integrationContext: {
+              rendererCache: runtimeContext.rendererCache,
+              componentInstanceId: resolution.componentInstanceId
+            }
+          },
+          runtimeContext.rendererCache
+        );
+        if (!foreignSubtreeRender) {
+          throw new Error(
+            `[ecopages] ${options.queueLabel} queued foreign subtree could not resolve its owning renderer.`
+          );
+        }
+        if ((foreignSubtreeRender.assets?.length ?? 0) > 0) {
+          collectedAssets.push(...foreignSubtreeRender.assets ?? []);
+        }
+        const resolvedHtml2 = foreignSubtreeRender.attachmentPolicy.kind === "first-element" && foreignSubtreeRender.rootAttributes ? options.applyAttributesToFirstElement(
+          foreignSubtreeRender.html,
+          foreignSubtreeRender.rootAttributes
+        ) : foreignSubtreeRender.html;
+        resolvedHtmlByToken.set(token, resolvedHtml2);
+        return resolvedHtml2;
+      } finally {
+        resolvingTokens.delete(token);
+      }
+    };
+    let resolvedHtml = options.html;
+    for (let index = 0; index < runtimeContext.queuedResolutions.length; index += 1) {
+      syncQueuedResolutions();
+      const resolution = runtimeContext.queuedResolutions[index];
+      if (!resolvedHtml.includes(resolution.token)) {
+        continue;
+      }
+      resolvedHtml = resolvedHtml.split(resolution.token).join(await resolveToken(resolution.token));
+    }
+    return {
+      assets: options.dedupeProcessedAssets(collectedAssets),
+      html: resolvedHtml
+    };
+  }
   async executeComponentRender(options) {
     const rendererCache = this.getRendererCache(options.input.integrationContext) ?? /* @__PURE__ */ new Map();
     const delegatedForeignChildRender = await this.resolveForeignChildInOwningRenderer({
@@ -167,12 +276,6 @@ class ForeignSubtreeExecutionService {
       integrationContext: integrationContext ? { ...integrationContext, rendererCache: sharedRendererCache } : { rendererCache: sharedRendererCache }
     };
   }
-  /**
-   * Returns the delegatable owning renderer integration for one component.
-   *
-   * The pseudo `html` integration marks document-shell ownership only and does
-   * not participate in component-level foreign subtree execution.
-   */
   getForeignOwnerIntegrationName(component, currentIntegrationName) {
     const integrationName = component.config?.integration ?? component.config?.__eco?.integration;
     if (!integrationName || integrationName === "html" || integrationName === currentIntegrationName) {
@@ -195,7 +298,7 @@ class ForeignSubtreeExecutionService {
       input: options.input,
       rendererCache: options.rendererCache,
       getOwningRenderer: options.getOwningRenderer,
-      run: (owningRenderer, delegatedInput) => owningRenderer.renderForeignSubtree(delegatedInput)
+      run: async (owningRenderer, delegatedInput) => toForeignSubtreeRenderPayload(await owningRenderer.renderComponentWithForeignChildren(delegatedInput))
     });
   }
   async runInForeignOwningRenderer(options) {
@@ -227,7 +330,33 @@ class ForeignSubtreeExecutionService {
     }
     return resolvedHtml;
   }
+  createForeignSubtreeToken(tokenPrefix, runtimeContext, foreignSubtreeId) {
+    return `${tokenPrefix}${runtimeContext.componentInstanceScope ?? "root"}__${foreignSubtreeId}__`;
+  }
+  ensureRuntimeContext(options) {
+    let integrationContext;
+    if (typeof options.renderInput.integrationContext === "object" && options.renderInput.integrationContext !== null) {
+      integrationContext = options.renderInput.integrationContext;
+    } else {
+      integrationContext = {};
+    }
+    const existingRuntimeContext = integrationContext[options.runtimeContextKey];
+    if (typeof existingRuntimeContext !== "object" || existingRuntimeContext === null) {
+      integrationContext[options.runtimeContextKey] = options.createRuntimeContext?.(integrationContext, options.rendererCache) ?? {
+        rendererCache: options.rendererCache,
+        componentInstanceScope: integrationContext.componentInstanceId,
+        nextForeignSubtreeId: 0,
+        queuedResolutions: []
+      };
+    } else {
+      existingRuntimeContext.rendererCache = options.rendererCache;
+    }
+    integrationContext.rendererCache = options.rendererCache;
+    options.renderInput.integrationContext = integrationContext;
+    return integrationContext[options.runtimeContextKey];
+  }
 }
 export {
-  ForeignSubtreeExecutionService
+  ForeignSubtreeExecutionService,
+  toForeignSubtreeRenderPayload
 };

package/src/route-renderer/orchestration/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/global-injector-assets.service.js

@@ -0,0 +1,32 @@
+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";
+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);
+}
+export {
+  buildGlobalInjectorAssets
+};

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

@@ -4,17 +4,16 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, PagePackageResult, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 import { HtmlTransformerService } from '../../services/html/html-transformer.service.js';
 import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
 import { HttpError } from '../../errors/http-error.js';
 import { DependencyResolverService } from '../page-loading/dependency-resolver.js';
 import { PageModuleLoaderService } from '../page-loading/page-module-loader.js';
-import { type RouteHtmlFinalization, RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
+import { RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
 import type { ForeignChildRuntime } from './component-render-context.js';
-import { ForeignSubtreeExecutionService, type ForeignSubtreeExecutionOwningRenderer } from './foreign-subtree-execution.service.js';
-import { type QueuedForeignSubtreeResolutionContext } from './queued-foreign-subtree-resolution.service.js';
+import { ForeignSubtreeExecutionService, type ForeignSubtreeExecutionOwningRenderer, type ForeignSubtreeQueuedHtmlOptions, type QueuedForeignSubtreeResolutionContext } from './foreign-subtree-execution.service.js';
 /**
  * Controls how one route module is loaded outside the normal render path.
  *
@@ -59,7 +58,15 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     protected pageModuleLoaderService: PageModuleLoaderService;
     protected routeRenderOrchestrator: RouteRenderOrchestrator;
     protected readonly foreignSubtreeExecutionService: ForeignSubtreeExecutionService;
+    /**
+     * Serializes route and view renders that mutate `htmlTransformer` state.
+     *
+     * Integration renderers are cached per integration, so concurrent static builds
+     * and overlapping SSR requests must not share one transformer page package.
+     */
+    private renderExclusiveChain;
     protected DOC_TYPE: string;
+    private runRenderExclusive;
     /**
      * Loads one route module through the owning renderer's import path.
      *
@@ -69,34 +76,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * with raw transpiler access.
      */
     loadPageModule(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
-    /**
-     * Reads the execution-scoped owning-renderer cache from one render input.
-     *
-     * Shared page/layout/document shell helpers pass one cache through
-     * `integrationContext` so repeated delegation to the same foreign integration
-     * can reuse a single initialized renderer instance during one render flow.
-     * The cache is deliberately scoped to the current render execution rather than
-     * stored on the renderer, which avoids leaking mutable integration state across
-     * requests while still preventing redundant renderer initialization.
-     *
-     * @param integrationContext - Optional render context carried with one render input.
-     * @returns The current execution cache when present.
-     */
-    private getOwningRendererCache;
-    private getForeignOwnerIntegrationName;
-    /**
-     * Attaches an execution-scoped owning-renderer cache to one render input.
-     *
-     * Foreign-owned page, layout, or document shells may delegate several times in
-     * the same render flow. Threading the cache through `integrationContext`
-     * preserves renderer reuse without changing the public render input contract.
-     * Existing integration-specific context is preserved and augmented.
-     *
-     * @param input - Original render input.
-     * @param rendererCache - Execution-scoped renderer cache to propagate.
-     * @returns Render input augmented with the shared renderer cache.
-     */
-    private withOwningRendererCache;
     protected getRendererModuleValue(key: string): unknown;
     protected getRendererModuleString(key: string): string | undefined;
     protected getRendererBootstrapDependencies(partial?: boolean): ProcessedAsset[];
@@ -219,20 +198,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         documentProps?: Record<string, unknown>;
         transformDocumentHtml?: (html: string) => string;
     }): Promise<string>;
-    private composeDocumentShell;
-    /**
-     * Renders one string-first component with serialized children and collects its assets.
-     *
-     * String-oriented integrations frequently share the same component contract:
-     * pass serialized children through props, coerce the render result to HTML, and
-     * attach any component-scoped dependencies. This helper centralizes that flow
-     * so integrations can opt into shared orchestration without repeating the same
-     * string-render boilerplate.
-     *
-     * @param input - Component render input.
-     * @param component - String-oriented component implementation to execute.
-     * @returns Structured component render result for orchestration paths.
-     */
     protected renderStringComponentWithSerializedChildren(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
     protected getForeignSubtreeTokenPrefix(): string;
     protected getForeignSubtreeResolutionContextKey(): string;
@@ -244,6 +209,10 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         createRuntimeContext?: (integrationContext: BaseIntegrationContext & Record<string, unknown>, rendererCache: Map<string, unknown>) => TContext;
     }): ForeignChildRuntime;
     protected getQueuedForeignSubtreeResolutionContext<TContext extends QueuedForeignSubtreeResolutionContext>(input: ComponentRenderInput): TContext | undefined;
+    protected resolveQueuedForeignSubtreeHtml<TContext extends QueuedForeignSubtreeResolutionContext>(html: string, runtimeContext: TContext | undefined, renderQueuedChildren: ForeignSubtreeQueuedHtmlOptions<TContext>['renderQueuedChildren'], queueLabel?: string): Promise<{
+        assets: ProcessedAsset[];
+        html: string;
+    }>;
     /**
      * Renders a string-first component, then resolves any queued foreign
      * boundaries before returning final component HTML.
@@ -350,8 +319,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         routeOptions: RouteRendererOptions;
     }): Promise<ComponentRenderResult | undefined>;
     protected renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
-    protected getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization;
-    protected transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
+    protected transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<RouteRendererBody>;
     /**
      * Prepares the render options for the integration renderer.
      * It imports the page file, collects dependencies, and prepares the render options.
@@ -413,6 +381,8 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * other runtime coordination markers without relying on script sniffing.
      */
     protected getDocumentAttributes(_renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
+    protected applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    protected applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
     /**
      * Returns declarative HTML fragments that core should inject into the final document.
      *
@@ -451,12 +421,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * renderer's nested foreign-child handoff.
      */
     renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-    /**
-     * Compatibility foreign-subtree contract that exposes a narrower payload shape for
-     * future route-composition work while preserving the current
-     * `renderComponentWithForeignChildren()` runtime semantics.
-     */
-    renderForeignSubtree(input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload>;
     private normalizeComponentRenderOutput;
     protected normalizeUnresolvedMarkerArtifactHtml(html: string): string;
     /**