@ecopages/core 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/route-renderer/orchestration/queued-boundary-runtime.service.d.ts

@@ -0,0 +1,93 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent } from '../../types/public-types.js';
+import type { ComponentBoundaryRuntime } from './component-render-context.js';
+export type QueuedBoundaryDecisionInput = {
+    currentIntegration: string;
+    targetIntegration?: string;
+    component: EcoComponent;
+    props: Record<string, unknown>;
+};
+export type QueuedBoundaryResolution = {
+    token: string;
+    component: EcoComponent;
+    props: Record<string, unknown>;
+    componentInstanceId: string;
+};
+/**
+ * Shared mutable state for one renderer-owned queued boundary runtime.
+ *
+ * Renderers that cannot resolve foreign boundaries inline can enqueue transport
+ * tokens during their initial render, then resolve those tokens against the
+ * owning renderer before returning final HTML.
+ */
+export type QueuedBoundaryRuntimeContext = {
+    rendererCache: Map<string, unknown>;
+    componentInstanceScope?: string;
+    nextBoundaryId: number;
+    queuedResolutions: QueuedBoundaryResolution[];
+};
+type QueuedBoundaryIntegrationContext = {
+    rendererCache?: Map<string, unknown>;
+    componentInstanceId?: string;
+    [key: string]: unknown;
+};
+type QueuedBoundaryChildRenderResult = {
+    assets: ProcessedAsset[];
+    html?: string;
+};
+/**
+ * Shared queue orchestration for renderer-owned boundary runtimes that emit
+ * temporary transport tokens during one render pass.
+ *
+ * The service keeps three responsibilities in one place:
+ * - storing per-render queue state on the active integration context
+ * - creating a `ComponentBoundaryRuntime` that enqueues foreign boundaries
+ * - resolving queued tokens back through the owning renderer before final HTML
+ *   leaves the current renderer
+ *
+ * Renderers still own framework-specific child rendering. This service only
+ * handles queue bookkeeping, recursion, cycle detection, and asset merging.
+ */
+export declare class QueuedBoundaryRuntimeService {
+    /**
+     * Reads the queued boundary runtime state previously attached to one render.
+     */
+    getRuntimeContext<TContext extends QueuedBoundaryRuntimeContext>(input: ComponentRenderInput, runtimeContextKey: string): TContext | undefined;
+    /**
+     * Creates the runtime hook used by `runWithComponentRenderContext()` for one
+     * renderer-owned queue.
+     *
+     * When the renderer decides a boundary must be handed off, the runtime returns
+     * a resolved transport token instead of rendering the foreign component inline.
+     */
+    createRuntime<TContext extends QueuedBoundaryRuntimeContext>(options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, unknown>;
+        runtimeContextKey: string;
+        tokenPrefix: string;
+        shouldQueueBoundary: (input: QueuedBoundaryDecisionInput) => boolean;
+        createRuntimeContext?: (integrationContext: QueuedBoundaryIntegrationContext, rendererCache: Map<string, unknown>) => TContext;
+    }): ComponentBoundaryRuntime;
+    /**
+     * Resolves every queued transport token in one renderer-owned HTML fragment.
+     *
+     * The caller supplies framework-specific child rendering, while this service
+     * handles recursive token replacement, cycle detection, root-attribute
+     * application, and merged asset collection.
+     */
+    resolveQueuedHtml<TContext extends QueuedBoundaryRuntimeContext>(options: {
+        html: string;
+        runtimeContext?: TContext;
+        queueLabel: string;
+        renderQueuedChildren: (children: unknown, runtimeContext: TContext, queuedResolutionsByToken: Map<string, QueuedBoundaryResolution>, resolveToken: (token: string) => Promise<string>) => Promise<QueuedBoundaryChildRenderResult>;
+        resolveBoundary: (input: ComponentRenderInput, rendererCache: Map<string, unknown>) => Promise<ComponentRenderResult | undefined>;
+        applyAttributesToFirstElement: (html: string, attributes: Record<string, string>) => string;
+        dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[];
+    }): Promise<{
+        assets: ProcessedAsset[];
+        html: string;
+    }>;
+    private createBoundaryToken;
+    private ensureRuntimeContext;
+}
+export {};

package/src/route-renderer/orchestration/queued-boundary-runtime.service.js

@@ -0,0 +1,155 @@
+class QueuedBoundaryRuntimeService {
+  /**
+   * Reads the queued boundary runtime state previously attached to one render.
+   */
+  getRuntimeContext(input, runtimeContextKey) {
+    const integrationContext = input.integrationContext;
+    const runtimeContext = integrationContext?.[runtimeContextKey];
+    if (typeof runtimeContext !== "object" || runtimeContext === null) {
+      return void 0;
+    }
+    return runtimeContext;
+  }
+  /**
+   * Creates the runtime hook used by `runWithComponentRenderContext()` for one
+   * renderer-owned queue.
+   *
+   * When the renderer decides a boundary must be handed off, the runtime returns
+   * a resolved transport token instead of rendering the foreign component inline.
+   */
+  createRuntime(options) {
+    const runtimeContext = this.ensureRuntimeContext(options);
+    const interceptBoundary = (input) => {
+      if (!options.shouldQueueBoundary(input)) {
+        return { kind: "inline" };
+      }
+      runtimeContext.nextBoundaryId += 1;
+      const boundaryId = runtimeContext.nextBoundaryId;
+      const token = this.createBoundaryToken(options.tokenPrefix, runtimeContext, boundaryId);
+      runtimeContext.queuedResolutions.push({
+        token,
+        component: input.component,
+        props: { ...input.props },
+        componentInstanceId: runtimeContext.componentInstanceScope ? `${runtimeContext.componentInstanceScope}_n_${boundaryId}` : `n_${boundaryId}`
+      });
+      return {
+        kind: "resolved",
+        value: token
+      };
+    };
+    return {
+      interceptBoundary,
+      interceptBoundarySync: interceptBoundary
+    };
+  }
+  /**
+   * Resolves every queued transport token in one renderer-owned HTML fragment.
+   *
+   * The caller supplies framework-specific child rendering, while this service
+   * handles recursive token replacement, cycle detection, root-attribute
+   * application, and merged asset collection.
+   */
+  async resolveQueuedHtml(options) {
+    if (!options.runtimeContext || options.runtimeContext.queuedResolutions.length === 0) {
+      return { assets: [], html: options.html };
+    }
+    const runtimeContext = options.runtimeContext;
+    const queuedResolutionsByToken = new Map(
+      runtimeContext.queuedResolutions.map((resolution) => [resolution.token, resolution])
+    );
+    const resolvedHtmlByToken = /* @__PURE__ */ new Map();
+    const resolvingTokens = /* @__PURE__ */ new Set();
+    const collectedAssets = [];
+    const resolveToken = async (token) => {
+      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} boundary queue contains a cycle or unresolved dependency links.`
+        );
+      }
+      resolvingTokens.add(token);
+      try {
+        const renderedChildren = await options.renderQueuedChildren(
+          resolution.props.children,
+          runtimeContext,
+          queuedResolutionsByToken,
+          resolveToken
+        );
+        if (renderedChildren.assets.length > 0) {
+          collectedAssets.push(...renderedChildren.assets);
+        }
+        const boundaryRender = await options.resolveBoundary(
+          {
+            component: resolution.component,
+            props: { ...resolution.props },
+            children: renderedChildren.html,
+            integrationContext: {
+              rendererCache: runtimeContext.rendererCache,
+              componentInstanceId: resolution.componentInstanceId
+            }
+          },
+          runtimeContext.rendererCache
+        );
+        if (!boundaryRender) {
+          throw new Error(
+            `[ecopages] ${options.queueLabel} queued boundary could not resolve its owning renderer.`
+          );
+        }
+        if ((boundaryRender.assets?.length ?? 0) > 0) {
+          collectedAssets.push(...boundaryRender.assets ?? []);
+        }
+        const resolvedHtml2 = boundaryRender.canAttachAttributes && boundaryRender.rootAttributes ? options.applyAttributesToFirstElement(boundaryRender.html, boundaryRender.rootAttributes) : boundaryRender.html;
+        resolvedHtmlByToken.set(token, resolvedHtml2);
+        return resolvedHtml2;
+      } finally {
+        resolvingTokens.delete(token);
+      }
+    };
+    let resolvedHtml = options.html;
+    for (const resolution of runtimeContext.queuedResolutions) {
+      if (!resolvedHtml.includes(resolution.token)) {
+        continue;
+      }
+      resolvedHtml = resolvedHtml.split(resolution.token).join(await resolveToken(resolution.token));
+    }
+    return {
+      assets: options.dedupeProcessedAssets(collectedAssets),
+      html: resolvedHtml
+    };
+  }
+  createBoundaryToken(tokenPrefix, runtimeContext, boundaryId) {
+    return `${tokenPrefix}${runtimeContext.componentInstanceScope ?? "root"}__${boundaryId}__`;
+  }
+  ensureRuntimeContext(options) {
+    let integrationContext;
+    if (typeof options.boundaryInput.integrationContext === "object" && options.boundaryInput.integrationContext !== null) {
+      integrationContext = options.boundaryInput.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,
+        nextBoundaryId: 0,
+        queuedResolutions: []
+      };
+    } else {
+      existingRuntimeContext.rendererCache = options.rendererCache;
+    }
+    integrationContext.rendererCache = options.rendererCache;
+    options.boundaryInput.integrationContext = integrationContext;
+    return integrationContext[options.runtimeContextKey];
+  }
+}
+export {
+  QueuedBoundaryRuntimeService
+};

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

@@ -1,73 +1,31 @@
-import { type ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
-import type { EcoComponent, IntegrationRendererRenderOptions, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import type { MarkerGraphContext } from '../component-graph/marker-graph-resolver.js';
-/**
- * Serializable graph context merged from render-time captured references and
- * optional explicit page-module graph metadata.
- */
-export type RenderExecutionGraphContext = {
-    propsByRef?: Record<string, Record<string, unknown>>;
-    slotChildrenByRef?: MarkerGraphContext['slotChildrenByRef'];
-};
+import type { IntegrationRendererRenderOptions, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 export interface CapturedHtmlRenderResult {
     body: RouteRendererBody;
     html: string;
-    graphContext: RenderExecutionGraphContext;
 }
 export interface FinalizeHtmlRenderOptions {
     html: string;
-    graphContext: RenderExecutionGraphContext;
-    componentsToResolve: EcoComponent[];
     componentRootAttributes?: Record<string, string>;
     documentAttributes?: Record<string, string>;
-    mergeAssets?: boolean;
 }
 export interface RenderExecutionCallbacks<C> {
     prepareRenderOptions(options: RouteRendererOptions): Promise<IntegrationRendererRenderOptions<C>>;
     render(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
-    getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
     getDocumentAttributes(renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
-    resolveMarkerGraphHtml(input: {
-        html: string;
-        componentsToResolve: EcoComponent[];
-        graphContext: RenderExecutionGraphContext;
-    }): Promise<{
-        html: string;
-        assets: ProcessedAsset[];
-    }>;
-    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
-    getProcessedDependencies(): ProcessedAsset[];
-    setProcessedDependencies(dependencies: ProcessedAsset[]): void;
     applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
     applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
     transformResponse(response: Response): Promise<RouteRendererBody>;
 }
-export interface FinalizeHtmlRenderCallbacks {
-    resolveMarkerGraphHtml(input: {
-        html: string;
-        componentsToResolve: EcoComponent[];
-        graphContext: RenderExecutionGraphContext;
-    }): Promise<{
-        html: string;
-        assets: ProcessedAsset[];
-    }>;
-    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
-    getProcessedDependencies(): ProcessedAsset[];
-    setProcessedDependencies(dependencies: ProcessedAsset[]): void;
-    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
-    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
-}
 /**
  * Executes the main post-preparation rendering flow for integration renderers.
  *
  * This service owns the orchestration that happens after normalized render
- * options have been prepared: the first render pass, graph-context capture,
- * deferred marker resolution, root-attribute application, and final HTML
- * transformation into a response body stream.
+ * options have been prepared: one render pass, unresolved boundary-marker
+ * enforcement, root-attribute application, and final HTML transformation into
+ * a response body stream.
  */
 export declare class RenderExecutionService {
-    captureHtmlRender(currentIntegrationName: string, boundaryContext: ComponentRenderBoundaryContext, render: () => Promise<RouteRendererBody>): Promise<CapturedHtmlRenderResult>;
+    captureHtmlRender(render: () => Promise<RouteRendererBody>): Promise<CapturedHtmlRenderResult>;
     /**
      * Executes one integration render pass and returns the final route render
      * result.
@@ -78,28 +36,8 @@ export declare class RenderExecutionService {
      * @param callbacks Renderer-specific hooks required during execution.
      * @returns Final route render output with body and cache strategy.
      */
-    execute<C = unknown>(options: RouteRendererOptions, currentIntegrationName: string, callbacks: RenderExecutionCallbacks<C>): Promise<RouteRenderResult>;
+    execute<C = unknown>(options: RouteRendererOptions, callbacks: RenderExecutionCallbacks<C>): Promise<RouteRenderResult>;
     private captureRenderedBody;
-    /**
-     * Merges captured render-time graph references with any explicit graph context
-     * provided by the page module.
-     *
-     * @param capturedGraphContext Graph context captured from the first render pass.
-     * @param explicitGraphContext Optional page-module graph metadata.
-     * @returns Merged graph context used during marker resolution.
-     */
-    mergeGraphContext(capturedGraphContext: RenderExecutionGraphContext, explicitGraphContext?: RenderExecutionGraphContext): RenderExecutionGraphContext;
-    finalizeHtmlRender(options: FinalizeHtmlRenderOptions, callbacks: FinalizeHtmlRenderCallbacks): Promise<{
-        html: string;
-        assets: ProcessedAsset[];
-    }>;
-    /**
-     * Returns the component set that participates in marker graph resolution for a
-     * render pass.
-     *
-     * @typeParam C Integration render output element type.
-     * @param renderOptions Normalized render options for the pass.
-     * @returns Ordered component list for graph registry construction.
-     */
-    private getComponentsToResolve;
+    finalizeHtmlRender(options: FinalizeHtmlRenderOptions, callbacks: Pick<RenderExecutionCallbacks<unknown>, 'applyAttributesToHtmlElement' | 'applyAttributesToFirstBodyElement'>): Promise<string>;
+    private applyFinalHtmlAttributes;
 }

package/src/route-renderer/orchestration/render-execution.service.js

@@ -1,38 +1,11 @@
-import {
-  runWithComponentRenderContext
-} from "../../eco/component-render-context.js";
-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 restoreEscapedComponentMarkers(html) {
-  return html.replace(
-    /&(?:amp;)?lt;eco-marker\b[\s\S]*?&(?:amp;)?gt;&(?:amp;)?lt;\/eco-marker&(?:amp;)?gt;/g,
-    (marker) => decodeHtmlEntities(marker)
-  );
-}
-const MAX_MARKER_RESOLUTION_PASSES = 10;
+import { inspectBoundaryArtifactHtml } from "./render-output.utils.js";
 class RenderExecutionService {
-  async captureHtmlRender(currentIntegrationName, boundaryContext, render) {
-    const renderExecution = await runWithComponentRenderContext(
-      {
-        currentIntegration: currentIntegrationName,
-        boundaryContext
-      },
-      async () => {
-        const renderedBody = await render();
-        return await this.captureRenderedBody(renderedBody);
-      }
-    );
+  async captureHtmlRender(render) {
+    const renderedBody = await render();
+    const capturedRender = await this.captureRenderedBody(renderedBody);
     return {
-      body: renderExecution.value.body,
-      html: renderExecution.value.html,
-      graphContext: renderExecution.graphContext
+      body: capturedRender.body,
+      html: capturedRender.html
     };
   }
   /**
@@ -45,17 +18,19 @@ class RenderExecutionService {
    * @param callbacks Renderer-specific hooks required during execution.
    * @returns Final route render output with body and cache strategy.
    */
-  async execute(options, currentIntegrationName, callbacks) {
+  async execute(options, callbacks) {
     const renderOptions = await callbacks.prepareRenderOptions(options);
     const shouldApplyComponentRootAttributes = renderOptions.componentRender?.canAttachAttributes && renderOptions.componentRender.rootAttributes && Object.keys(renderOptions.componentRender.rootAttributes).length > 0;
-    const renderExecution = await this.captureHtmlRender(
-      currentIntegrationName,
-      callbacks.getComponentRenderBoundaryContext(),
-      async () => callbacks.render(renderOptions)
-    );
-    const normalizedCapturedHtml = restoreEscapedComponentMarkers(renderExecution.html);
+    const renderExecution = await this.captureHtmlRender(async () => callbacks.render(renderOptions));
+    const boundaryArtifacts = inspectBoundaryArtifactHtml(renderExecution.html);
     const documentAttributes = callbacks.getDocumentAttributes(renderOptions);
-    const canReuseCapturedBody = !normalizedCapturedHtml.includes("<eco-marker") && !shouldApplyComponentRootAttributes && !(documentAttributes && Object.keys(documentAttributes).length > 0);
+    const hasBoundaryMarkerHtml = boundaryArtifacts.hasUnresolvedBoundaryArtifacts;
+    if (hasBoundaryMarkerHtml) {
+      throw new Error(
+        "[ecopages] Route render returned unresolved boundary artifact HTML. Full-route unresolved-boundary fallback has been removed; resolve mixed boundaries inside renderComponentBoundary()."
+      );
+    }
+    const canReuseCapturedBody = !hasBoundaryMarkerHtml && !shouldApplyComponentRootAttributes && !(documentAttributes && Object.keys(documentAttributes).length > 0);
     if (canReuseCapturedBody) {
       const body2 = await callbacks.transformResponse(
         new Response(renderExecution.body, {
@@ -69,23 +44,19 @@ class RenderExecutionService {
         cacheStrategy: renderOptions.cacheStrategy
       };
     }
-    const componentGraphContext = this.mergeGraphContext(
-      renderExecution.graphContext,
-      renderOptions.componentGraphContext
-    );
     const finalization = await this.finalizeHtmlRender(
       {
-        html: normalizedCapturedHtml,
-        graphContext: componentGraphContext,
-        componentsToResolve: this.getComponentsToResolve(renderOptions),
+        html: boundaryArtifacts.normalizedHtml,
         componentRootAttributes: shouldApplyComponentRootAttributes ? renderOptions.componentRender?.rootAttributes : void 0,
-        documentAttributes,
-        mergeAssets: true
+        documentAttributes
       },
-      callbacks
+      {
+        applyAttributesToHtmlElement: callbacks.applyAttributesToHtmlElement,
+        applyAttributesToFirstBodyElement: callbacks.applyAttributesToFirstBodyElement
+      }
     );
     const body = await callbacks.transformResponse(
-      new Response(finalization.html, {
+      new Response(finalization, {
         headers: {
           "Content-Type": "text/html"
         }
@@ -116,74 +87,18 @@ class RenderExecutionService {
       html: await new Response(capturedBody).text()
     };
   }
-  /**
-   * Merges captured render-time graph references with any explicit graph context
-   * provided by the page module.
-   *
-   * @param capturedGraphContext Graph context captured from the first render pass.
-   * @param explicitGraphContext Optional page-module graph metadata.
-   * @returns Merged graph context used during marker resolution.
-   */
-  mergeGraphContext(capturedGraphContext, explicitGraphContext) {
-    return {
-      propsByRef: {
-        ...capturedGraphContext.propsByRef ?? {},
-        ...explicitGraphContext?.propsByRef ?? {}
-      },
-      slotChildrenByRef: {
-        ...capturedGraphContext.slotChildrenByRef ?? {},
-        ...explicitGraphContext?.slotChildrenByRef ?? {}
-      }
-    };
-  }
   async finalizeHtmlRender(options, callbacks) {
-    let renderedHtml = restoreEscapedComponentMarkers(options.html);
-    let markerAssets = [];
-    for (let pass = 0; pass < MAX_MARKER_RESOLUTION_PASSES; pass += 1) {
-      if (!renderedHtml.includes("<eco-marker")) {
-        break;
-      }
-      const markerResolution = await callbacks.resolveMarkerGraphHtml({
-        html: renderedHtml,
-        componentsToResolve: options.componentsToResolve,
-        graphContext: options.graphContext
-      });
-      const resolvedHtml = restoreEscapedComponentMarkers(markerResolution.html);
-      markerAssets = callbacks.dedupeProcessedAssets([...markerAssets, ...markerResolution.assets]);
-      if (options.mergeAssets !== false && markerResolution.assets.length > 0) {
-        const mergedDependencies = callbacks.dedupeProcessedAssets([
-          ...callbacks.getProcessedDependencies(),
-          ...markerResolution.assets
-        ]);
-        callbacks.setProcessedDependencies(mergedDependencies);
-      }
-      if (resolvedHtml === renderedHtml) {
-        renderedHtml = resolvedHtml;
-        break;
-      }
-      renderedHtml = resolvedHtml;
-    }
+    return this.applyFinalHtmlAttributes(options.html, options, callbacks);
+  }
+  applyFinalHtmlAttributes(html, options, callbacks) {
+    let renderedHtml = html;
     if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
       renderedHtml = callbacks.applyAttributesToFirstBodyElement(renderedHtml, options.componentRootAttributes);
     }
     if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
       renderedHtml = callbacks.applyAttributesToHtmlElement(renderedHtml, options.documentAttributes);
     }
-    return {
-      html: renderedHtml,
-      assets: markerAssets
-    };
-  }
-  /**
-   * Returns the component set that participates in marker graph resolution for a
-   * render pass.
-   *
-   * @typeParam C Integration render output element type.
-   * @param renderOptions Normalized render options for the pass.
-   * @returns Ordered component list for graph registry construction.
-   */
-  getComponentsToResolve(renderOptions) {
-    return renderOptions.Layout ? [renderOptions.HtmlTemplate, renderOptions.Layout, renderOptions.Page] : [renderOptions.HtmlTemplate, renderOptions.Page];
+    return renderedHtml;
   }
 }
 export {

package/src/route-renderer/orchestration/render-output.utils.d.ts

@@ -0,0 +1,46 @@
+import type { EcoComponent } from '../../types/public-types.js';
+/**
+ * Returns `true` when `value` is a thenable (Promise-like) object.
+ *
+ * Used to transparently handle both synchronous and asynchronous component
+ * render results without requiring every caller to branch on `instanceof Promise`.
+ *
+ * @typeParam T Expected resolved type of the thenable.
+ */
+export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;
+/**
+ * Injects `data-eco-trigger` into the first real HTML element opening tag of
+ * a component's rendered output string.
+ *
+ * The scan skips over leading whitespace, HTML comments (`<!-- -->`), CDATA
+ * sections, and doctype declarations so that the attribute is always placed on
+ * the first actual element — not spurious markup that can precede it.
+ *
+ * The insertion point is the end of the element's tag name, before any existing
+ * attributes or the closing `>`, which produces output like:
+ *
+ * ```html
+ * <my-element data-eco-trigger="eco-trigger-abc123" class="foo">…</my-element>
+ * ```
+ *
+ * When no eligible opening tag is found the original string is returned
+ * unchanged so callers never receive a broken fragment.
+ *
+ * @param content Rendered HTML string (or any value coercible to string).
+ * @param triggerId Stable trigger identifier produced by `buildResolvedLazyTriggers`.
+ */
+export declare function addTriggerAttribute(content: unknown, triggerId: string): string;
+/**
+ * Wraps rendered component output in a `<scripts-injector>` element that
+ * carries an inline injector map for the legacy (non-global-injector) path.
+ *
+ * @param content Rendered component HTML.
+ * @param lazyGroups Resolved lazy script groups attached to the component config.
+ */
+export declare function wrapWithScriptsInjector(content: unknown, lazyGroups: NonNullable<EcoComponent['config']>['_resolvedLazyScripts']): string;
+export declare function decodeHtmlEntities(value: string): string;
+export declare function normalizeBoundaryArtifactHtml(html: string): string;
+export declare function inspectBoundaryArtifactHtml(html: string): {
+    hasUnresolvedBoundaryArtifacts: boolean;
+    normalizedHtml: string;
+};

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

@@ -0,0 +1,65 @@
+import { buildInjectorMapScript } from "../../eco/lazy-injector-map.js";
+function isThenable(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function addTriggerAttribute(content, triggerId) {
+  const str = String(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 wrapWithScriptsInjector(content, lazyGroups) {
+  const wrappedContent = String(content);
+  const injectorMapScript = buildInjectorMapScript(lazyGroups ?? []);
+  return `<scripts-injector><script type="ecopages/injector-map">${injectorMapScript}<\/script>${wrappedContent}<\/scripts-injector>`;
+}
+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 normalizeBoundaryArtifactHtml(html) {
+  return html.replace(
+    /&(?:amp;)?lt;eco-marker\b[\s\S]*?&(?:amp;)?gt;&(?:amp;)?lt;\/eco-marker&(?:amp;)?gt;/g,
+    (marker) => decodeHtmlEntities(marker)
+  );
+}
+function inspectBoundaryArtifactHtml(html) {
+  const normalizedHtml = normalizeBoundaryArtifactHtml(html);
+  return {
+    normalizedHtml,
+    hasUnresolvedBoundaryArtifacts: normalizedHtml.includes("<eco-marker")
+  };
+}
+export {
+  addTriggerAttribute,
+  decodeHtmlEntities,
+  inspectBoundaryArtifactHtml,
+  isThenable,
+  normalizeBoundaryArtifactHtml,
+  wrapWithScriptsInjector
+};

package/src/route-renderer/orchestration/render-preparation.service.d.ts

@@ -1,7 +1,6 @@
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetStaticProps, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererOptions } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import { type ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
 type ResolvedPageModule = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
     getStaticProps?: GetStaticProps<Record<string, unknown>>;
@@ -29,11 +28,6 @@ export interface RenderPreparationCallbacks {
         component: EcoComponent;
         props: Record<string, unknown>;
     }): Promise<ComponentRenderResult>;
-    /**
-     * Returns the boundary policy context that should be active while rendering
-     * page-root component output during preparation.
-     */
-    getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
     setProcessedDependencies(dependencies: ProcessedAsset[]): void;
     dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
     createPageLocalsProxy(filePath: string): RouteRendererOptions['locals'];