@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

package/src/route-renderer/orchestration/component-render-context.js

@@ -0,0 +1,147 @@
+import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./render-output.utils.js";
+class ComponentRenderOutputRuntime {
+  finalizeComponentRender(component, content) {
+    const lazyTriggers = component.config?._resolvedLazyTriggers;
+    if (lazyTriggers && lazyTriggers.length > 0) {
+      return this.addTriggerToContent(content, lazyTriggers[0].triggerId);
+    }
+    const lazyGroups = component.config?._resolvedLazyScripts;
+    if (lazyGroups && lazyGroups.length > 0) {
+      return this.wrapContentWithScriptsInjector(content, lazyGroups);
+    }
+    return content;
+  }
+  addTriggerToContent(content, triggerId) {
+    if (isThenable(content)) {
+      return content.then((resolvedContent) => addTriggerAttribute(resolvedContent, triggerId));
+    }
+    return addTriggerAttribute(content, triggerId);
+  }
+  wrapContentWithScriptsInjector(content, lazyGroups) {
+    if (isThenable(content)) {
+      return content.then((resolvedContent) => wrapWithScriptsInjector(resolvedContent, lazyGroups));
+    }
+    return wrapWithScriptsInjector(content, lazyGroups);
+  }
+}
+class ContextualComponentRenderRuntime extends ComponentRenderOutputRuntime {
+  context;
+  constructor(context) {
+    super();
+    this.context = context;
+  }
+  applyForeignChildInterceptionResult(result) {
+    if (result.kind === "resolved") {
+      return result.value;
+    }
+    return void 0;
+  }
+  /**
+   * Resolves one foreign-child interception through the active runtime.
+   *
+   * The runtime may choose inline rendering or immediate resolved output.
+   */
+  interceptForeignChild(input) {
+    const foreignChildRuntimeInput = {
+      currentIntegration: this.context.currentIntegration,
+      targetIntegration: input.targetIntegration,
+      component: input.component,
+      props: input.props
+    };
+    const asyncInterception = this.context.foreignChildRuntime?.interceptForeignChild?.(foreignChildRuntimeInput);
+    if (asyncInterception !== void 0) {
+      if (isThenable(asyncInterception)) {
+        return asyncInterception.then((result) => this.applyForeignChildInterceptionResult(result));
+      }
+      return this.applyForeignChildInterceptionResult(asyncInterception);
+    }
+    const syncInterception = this.context.foreignChildRuntime?.interceptForeignChildSync?.(foreignChildRuntimeInput);
+    if (syncInterception === void 0) {
+      return void 0;
+    }
+    return this.applyForeignChildInterceptionResult(syncInterception);
+  }
+}
+const GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY = "__ECOPAGES_COMPONENT_RENDER_CONTEXT_STATE__";
+function getSharedContextScope() {
+  const globalProcess = globalThis.process;
+  if (globalProcess && typeof globalProcess === "object") {
+    return globalProcess;
+  }
+  return globalThis;
+}
+function getComponentRenderContextState() {
+  const sharedScope = getSharedContextScope();
+  sharedScope[GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY] ??= {
+    contextStack: [],
+    nodeContextStorage: null,
+    nodeContextStorageLoader: null
+  };
+  return sharedScope[GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY];
+}
+async function getContextStorage() {
+  const state = getComponentRenderContextState();
+  if (state.nodeContextStorage) {
+    return state.nodeContextStorage;
+  }
+  if (state.nodeContextStorageLoader) {
+    return state.nodeContextStorageLoader;
+  }
+  state.nodeContextStorageLoader = import("node:async_hooks").then((module) => {
+    const storage = new module.AsyncLocalStorage();
+    state.nodeContextStorage = {
+      getStore: () => storage.getStore(),
+      run: (store, callback) => storage.run(store, callback)
+    };
+    return state.nodeContextStorage;
+  }).catch(() => {
+    state.nodeContextStorage = null;
+    return null;
+  }).finally(() => {
+    state.nodeContextStorageLoader = null;
+  });
+  return state.nodeContextStorageLoader;
+}
+function getComponentRenderContext() {
+  const state = getComponentRenderContextState();
+  return state.nodeContextStorage?.getStore() ?? state.contextStack[state.contextStack.length - 1];
+}
+const componentRenderOutputRuntime = new ComponentRenderOutputRuntime();
+function interceptForeignChild(input) {
+  return getComponentRenderContext()?.interceptForeignChild(input);
+}
+function finalizeComponentRender(component, content) {
+  const renderContext = getComponentRenderContext();
+  return renderContext?.finalizeComponentRender(component, content) ?? componentRenderOutputRuntime.finalizeComponentRender(component, content);
+}
+async function runWithComponentRenderContext(input, render) {
+  const context = {
+    currentIntegration: input.currentIntegration,
+    foreignChildRuntime: input.foreignChildRuntime
+  };
+  const runtime = new ContextualComponentRenderRuntime(context);
+  context.interceptForeignChild = (deferredInput) => runtime.interceptForeignChild(deferredInput);
+  context.finalizeComponentRender = (component, content) => runtime.finalizeComponentRender(component, content);
+  const storage = await getContextStorage();
+  let value;
+  if (storage) {
+    value = await storage.run(context, render);
+  } else {
+    const state = getComponentRenderContextState();
+    state.contextStack.push(context);
+    try {
+      value = await render();
+    } finally {
+      state.contextStack.pop();
+    }
+  }
+  return {
+    value
+  };
+}
+export {
+  finalizeComponentRender,
+  getComponentRenderContext,
+  interceptForeignChild,
+  runWithComponentRenderContext
+};

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

@@ -0,0 +1,18 @@
+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 declare function mapDeclaredOwnershipGraph<T>(input: {
+    roots: DeclaredOwnershipRoot[];
+    currentIntegrationName: string;
+    mapNode: (node: DeclaredOwnershipNodeInput, children: T[]) => T;
+}): T[];

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

@@ -0,0 +1,34 @@
+function mapDeclaredOwnershipGraph(input) {
+  let nextSyntheticId = 0;
+  const mapComponent = (component, source, parentIntegrationName, lineage) => {
+    const integrationName = component.config?.integration ?? component.config?.__eco?.integration ?? parentIntegrationName;
+    const componentMeta = component.config?.__eco;
+    const isForeignToParent = integrationName !== parentIntegrationName;
+    const componentId = componentMeta?.id ?? componentMeta?.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, /* @__PURE__ */ new Set())
+  );
+}
+export {
+  mapDeclaredOwnershipGraph
+};

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

@@ -0,0 +1,108 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, ForeignSubtreeRenderPayload } from '../../types/public-types.js';
+import { type ForeignChildRuntime } from './component-render-context.js';
+import { QueuedForeignSubtreeResolutionService, type QueuedForeignSubtreeResolution, type QueuedForeignSubtreeResolutionContext } from './queued-foreign-subtree-resolution.service.js';
+export interface ForeignSubtreeExecutionOwningRenderer {
+    readonly name: string;
+    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    renderForeignSubtree(input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload>;
+}
+export interface ForeignSubtreeExecutionDecisionInput {
+    currentIntegration: string;
+    targetIntegration?: string;
+}
+export interface ForeignSubtreeExecutionRenderOptions {
+    currentIntegrationName: string;
+    input: ComponentRenderInput;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    normalizeComponentRenderOutput(result: ComponentRenderResult): ComponentRenderResult;
+    hasForeignChildDescendants(component: EcoComponent): boolean;
+    createForeignChildRuntime(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>;
+    }): ForeignChildRuntime;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+}
+export interface ForeignSubtreeQueuedRuntimeOptions<TContext extends QueuedForeignSubtreeResolutionContext> {
+    renderInput: ComponentRenderInput;
+    rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>;
+    runtimeContextKey: string;
+    tokenPrefix: string;
+    createRuntimeContext?: (integrationContext: BaseIntegrationContext & Record<string, unknown>, rendererCache: Map<string, unknown>) => TContext;
+}
+export interface ForeignSubtreeStringQueuedHtmlOptions {
+    currentIntegrationName: string;
+    renderInput: ComponentRenderInput;
+    html: string;
+    runtimeContextKey: string;
+    queueLabel: string;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
+    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
+}
+export interface ForeignSubtreeQueuedHtmlOptions<TContext extends QueuedForeignSubtreeResolutionContext> {
+    currentIntegrationName: string;
+    html: string;
+    runtimeContext?: TContext;
+    queueLabel: string;
+    renderQueuedChildren(children: unknown, runtimeContext: TContext, queuedResolutionsByToken: Map<string, QueuedForeignSubtreeResolution>, resolveToken: (token: string) => Promise<string>): Promise<{
+        assets: ProcessedAsset[];
+        html?: string;
+    }>;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
+    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
+}
+/**
+ * Executes one component render tree under Foreign Child support.
+ *
+ * This service owns the execution policy for mixed-integration component trees:
+ * it decides when a child stays inline, when it must delegate to an owning
+ * renderer, how one render-pass renderer cache is reused, and how queued
+ * Foreign Subtree tokens resolve back into final HTML.
+ */
+export declare class ForeignSubtreeExecutionService {
+    private readonly queuedForeignSubtreeResolutionService;
+    constructor(queuedForeignSubtreeResolutionService?: QueuedForeignSubtreeResolutionService);
+    /**
+     * Returns whether the current render pass must hand the child off to a foreign owner.
+     */
+    shouldDelegateForeignChild(input: ForeignSubtreeExecutionDecisionInput): boolean;
+    /**
+     * 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: string): ForeignChildRuntime;
+    getQueuedRuntimeContext<TContext extends QueuedForeignSubtreeResolutionContext>(input: ComponentRenderInput, runtimeContextKey: string): TContext | undefined;
+    createQueuedRuntime<TContext extends QueuedForeignSubtreeResolutionContext>(options: ForeignSubtreeQueuedRuntimeOptions<TContext>): ForeignChildRuntime;
+    /**
+     * Resolves a string-first renderer HTML fragment that may contain queued Foreign Subtree tokens.
+     */
+    resolveStringQueuedHtml<TContext extends QueuedForeignSubtreeResolutionContext>(options: ForeignSubtreeStringQueuedHtmlOptions): Promise<{
+        assets: ProcessedAsset[];
+        html: string;
+    }>;
+    resolveQueuedHtml<TContext extends QueuedForeignSubtreeResolutionContext>(options: ForeignSubtreeQueuedHtmlOptions<TContext>): Promise<{
+        assets: ProcessedAsset[];
+        html: string;
+    }>;
+    /**
+     * Executes one component render with Foreign Child support under the current integration.
+     */
+    executeComponentRender(options: ForeignSubtreeExecutionRenderOptions): Promise<ComponentRenderResult>;
+    private getRendererCache;
+    private withRendererCache;
+    /**
+     * 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.
+     */
+    private getForeignOwnerIntegrationName;
+    private resolveForeignChildInOwningRenderer;
+    private resolveForeignSubtreeInOwningRenderer;
+    private runInForeignOwningRenderer;
+    resolveQueuedTokens(html: string, queuedResolutionsByToken: Map<string, QueuedForeignSubtreeResolution>, resolveToken: (token: string) => Promise<string>): Promise<string>;
+}

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

@@ -0,0 +1,206 @@
+import {
+  getComponentRenderContext,
+  runWithComponentRenderContext
+} from "./component-render-context.js";
+import {
+  QueuedForeignSubtreeResolutionService
+} from "./queued-foreign-subtree-resolution.service.js";
+class ForeignSubtreeExecutionService {
+  queuedForeignSubtreeResolutionService;
+  constructor(queuedForeignSubtreeResolutionService = new QueuedForeignSubtreeResolutionService()) {
+    this.queuedForeignSubtreeResolutionService = queuedForeignSubtreeResolutionService;
+  }
+  /**
+   * 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)) {
+        return { kind: "inline" };
+      }
+      throw new Error(
+        `[ecopages] ${rendererName} renderer crossed into ${input.targetIntegration} without a renderer-owned foreign-child runtime. Override createForeignChildRuntime() to resolve foreign children inside the owning renderer.`
+      );
+    };
+    return {
+      interceptForeignChild,
+      interceptForeignChildSync: interceptForeignChild
+    };
+  }
+  getQueuedRuntimeContext(input, runtimeContextKey) {
+    return this.queuedForeignSubtreeResolutionService.getRuntimeContext(input, runtimeContextKey);
+  }
+  createQueuedRuntime(options) {
+    return this.queuedForeignSubtreeResolutionService.createRuntime({
+      renderInput: options.renderInput,
+      rendererCache: options.rendererCache,
+      runtimeContextKey: options.runtimeContextKey,
+      tokenPrefix: options.tokenPrefix,
+      shouldQueueForeignChild: (input) => this.shouldDelegateForeignChild(input),
+      createRuntimeContext: options.createRuntimeContext
+    });
+  }
+  /**
+   * Resolves a string-first renderer HTML fragment that may contain queued Foreign Subtree tokens.
+   */
+  async resolveStringQueuedHtml(options) {
+    const runtimeContext = this.getQueuedRuntimeContext(options.renderInput, options.runtimeContextKey);
+    return this.resolveQueuedHtml({
+      currentIntegrationName: options.currentIntegrationName,
+      html: options.html,
+      runtimeContext,
+      queueLabel: options.queueLabel,
+      renderQueuedChildren: async (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => {
+        if (children === void 0) {
+          return { assets: [], html: void 0 };
+        }
+        const html = await this.resolveQueuedTokens(
+          typeof children === "string" ? children : String(children ?? ""),
+          queuedResolutionsByToken,
+          resolveToken
+        );
+        return { assets: [], html };
+      },
+      getOwningRenderer: options.getOwningRenderer,
+      applyAttributesToFirstElement: options.applyAttributesToFirstElement,
+      dedupeProcessedAssets: options.dedupeProcessedAssets
+    });
+  }
+  async resolveQueuedHtml(options) {
+    return this.queuedForeignSubtreeResolutionService.resolveQueuedHtml({
+      html: options.html,
+      runtimeContext: options.runtimeContext,
+      queueLabel: options.queueLabel,
+      renderQueuedChildren: options.renderQueuedChildren,
+      resolveForeignSubtree: (input, rendererCache) => this.resolveForeignSubtreeInOwningRenderer({
+        currentIntegrationName: options.currentIntegrationName,
+        input,
+        rendererCache,
+        getOwningRenderer: options.getOwningRenderer
+      }),
+      applyAttributesToFirstElement: options.applyAttributesToFirstElement,
+      dedupeProcessedAssets: options.dedupeProcessedAssets
+    });
+  }
+  /**
+   * Executes one component render with Foreign Child support under the current integration.
+   */
+  async executeComponentRender(options) {
+    const rendererCache = this.getRendererCache(options.input.integrationContext) ?? /* @__PURE__ */ new Map();
+    const delegatedForeignChildRender = await this.resolveForeignChildInOwningRenderer({
+      currentIntegrationName: options.currentIntegrationName,
+      input: options.input,
+      rendererCache,
+      getOwningRenderer: options.getOwningRenderer
+    });
+    if (delegatedForeignChildRender) {
+      return delegatedForeignChildRender;
+    }
+    const hasForeignChildren = options.hasForeignChildDescendants(options.input.component);
+    const activeRenderContext = getComponentRenderContext();
+    if (!hasForeignChildren) {
+      if (!activeRenderContext || activeRenderContext.currentIntegration === options.currentIntegrationName) {
+        return options.normalizeComponentRenderOutput(await options.renderComponent(options.input));
+      }
+      const sameIntegrationExecution = await runWithComponentRenderContext(
+        {
+          currentIntegration: options.currentIntegrationName
+        },
+        async () => options.renderComponent(options.input)
+      );
+      return options.normalizeComponentRenderOutput(sameIntegrationExecution.value);
+    }
+    const execution = await runWithComponentRenderContext(
+      {
+        currentIntegration: options.currentIntegrationName,
+        foreignChildRuntime: options.createForeignChildRuntime({
+          renderInput: options.input,
+          rendererCache
+        })
+      },
+      async () => options.renderComponent(options.input)
+    );
+    return options.normalizeComponentRenderOutput(execution.value);
+  }
+  getRendererCache(integrationContext) {
+    if (integrationContext?.rendererCache instanceof Map) {
+      return integrationContext.rendererCache;
+    }
+    return void 0;
+  }
+  withRendererCache(input, rendererCache) {
+    const integrationContext = input.integrationContext;
+    const sharedRendererCache = rendererCache;
+    return {
+      ...input,
+      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) {
+      return void 0;
+    }
+    return integrationName;
+  }
+  async resolveForeignChildInOwningRenderer(options) {
+    return await this.runInForeignOwningRenderer({
+      currentIntegrationName: options.currentIntegrationName,
+      input: options.input,
+      rendererCache: options.rendererCache,
+      getOwningRenderer: options.getOwningRenderer,
+      run: (owningRenderer, delegatedInput) => owningRenderer.renderComponentWithForeignChildren(delegatedInput)
+    });
+  }
+  async resolveForeignSubtreeInOwningRenderer(options) {
+    return await this.runInForeignOwningRenderer({
+      currentIntegrationName: options.currentIntegrationName,
+      input: options.input,
+      rendererCache: options.rendererCache,
+      getOwningRenderer: options.getOwningRenderer,
+      run: (owningRenderer, delegatedInput) => owningRenderer.renderForeignSubtree(delegatedInput)
+    });
+  }
+  async runInForeignOwningRenderer(options) {
+    const foreignOwnerIntegrationName = this.getForeignOwnerIntegrationName(
+      options.input.component,
+      options.currentIntegrationName
+    );
+    if (!foreignOwnerIntegrationName) {
+      return void 0;
+    }
+    const owningRenderer = options.getOwningRenderer(foreignOwnerIntegrationName, options.rendererCache);
+    if (owningRenderer.name === options.currentIntegrationName) {
+      return void 0;
+    }
+    return await options.run(owningRenderer, this.withRendererCache(options.input, options.rendererCache));
+  }
+  async resolveQueuedTokens(html, queuedResolutionsByToken, resolveToken) {
+    let resolvedHtml = html;
+    for (const token of queuedResolutionsByToken.keys()) {
+      if (!resolvedHtml.includes(token)) {
+        continue;
+      }
+      resolvedHtml = resolvedHtml.split(token).join(await resolveToken(token));
+    }
+    return resolvedHtml;
+  }
+}
+export {
+  ForeignSubtreeExecutionService
+};