@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

package/src/route-renderer/orchestration/document-shell/document-shell-render.service.js

@@ -0,0 +1,148 @@
+import {
+  HtmlTransformerService
+} from "../../../services/html/html-transformer.service.js";
+function resolveDocumentShellLayouts(input) {
+  if (input.layouts && input.layouts.length > 0) {
+    return input.layouts;
+  }
+  return input.layout ? [input.layout] : [];
+}
+function resolveComponentIntegrationName(component) {
+  return component.config?.integration ?? component.config?.__eco?.integration ?? "ecopages";
+}
+async function composeSequentialLayoutChildren(context) {
+  if (!context.primaryRender) {
+    throw new Error("[ecopages] composeSequentialLayoutChildren requires primaryRender.");
+  }
+  let children = context.primaryRender.html;
+  const layoutRenders = [];
+  for (const layout of [...context.layouts].reverse()) {
+    const layoutRender = await context.renderComponentWithForeignChildren({
+      component: layout.component,
+      props: layout.props ?? {},
+      children,
+      integrationContext: { rendererCache: context.rendererCache }
+    });
+    layoutRenders.push(layoutRender);
+    children = layoutRender.html;
+  }
+  return {
+    children,
+    layoutRenders
+  };
+}
+async function composeDocumentShell(dependencies, input) {
+  const rendererCache = /* @__PURE__ */ new Map();
+  const layouts = resolveDocumentShellLayouts(input);
+  const composeChildren = input.composeChildren ?? composeSequentialLayoutChildren;
+  const usesCustomComposeChildren = input.composeChildren !== void 0;
+  let primaryRender;
+  let children;
+  let layoutRenders;
+  if (usesCustomComposeChildren) {
+    const composed = await composeChildren({
+      primaryComponent: input.primaryComponent,
+      primaryProps: input.primaryProps,
+      layouts,
+      rendererCache,
+      renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren
+    });
+    children = composed.children;
+    layoutRenders = composed.layoutRenders;
+    primaryRender = composed.primaryRender ?? {
+      html: typeof composed.children === "string" ? composed.children : "",
+      assets: [],
+      canAttachAttributes: true,
+      rootTag: "main",
+      integrationName: resolveComponentIntegrationName(input.primaryComponent)
+    };
+  } else {
+    primaryRender = await dependencies.renderComponentWithForeignChildren({
+      component: input.primaryComponent,
+      props: input.primaryProps,
+      integrationContext: { rendererCache }
+    });
+    const composed = await composeChildren({
+      primaryComponent: input.primaryComponent,
+      primaryProps: input.primaryProps,
+      primaryRender,
+      layouts,
+      rendererCache,
+      renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren
+    });
+    children = composed.children;
+    layoutRenders = composed.layoutRenders;
+  }
+  const documentRender = await dependencies.renderComponentWithForeignChildren({
+    component: input.htmlTemplate,
+    props: input.documentProps,
+    children,
+    integrationContext: { rendererCache }
+  });
+  dependencies.appendProcessedDependencies(
+    primaryRender.assets,
+    ...layoutRenders.map((layoutRender) => layoutRender.assets),
+    documentRender.assets
+  );
+  return {
+    documentHtml: documentRender.html
+  };
+}
+function applyDocumentShellAttributeStamping(html, stamping, options) {
+  let nextHtml = html;
+  if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
+    nextHtml = stamping.applyAttributesToFirstBodyElement(nextHtml, options.componentRootAttributes);
+  }
+  if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
+    nextHtml = stamping.applyAttributesToHtmlElement(nextHtml, options.documentAttributes);
+  }
+  return nextHtml;
+}
+async function renderPageDocumentShell(dependencies, input, docType) {
+  const { documentHtml: composedDocumentHtml } = await composeDocumentShell(dependencies, {
+    primaryComponent: input.page.component,
+    primaryProps: input.page.props,
+    layout: input.layout,
+    layouts: input.layouts,
+    composeChildren: input.composeChildren,
+    htmlTemplate: input.htmlTemplate,
+    documentProps: {
+      metadata: input.metadata,
+      pageProps: input.pageProps,
+      ...input.documentProps ?? {}
+    }
+  });
+  const documentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(composedDocumentHtml) : composedDocumentHtml;
+  return `${docType}${documentHtml}`;
+}
+async function finalizeDocumentShellHtml(htmlTransformer, options) {
+  const html = applyDocumentShellAttributeStamping(
+    options.html,
+    {
+      applyAttributesToFirstBodyElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToFirstBodyElement(nextHtml, attributes),
+      applyAttributesToHtmlElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToHtmlElement(nextHtml, attributes)
+    },
+    {
+      componentRootAttributes: options.componentRootAttributes,
+      documentAttributes: options.documentAttributes
+    }
+  );
+  const shouldTransform = options.transformHtml ?? !options.partial;
+  if (!shouldTransform) {
+    return html;
+  }
+  const transformedResponse = await htmlTransformer.transform(
+    new Response(html, {
+      headers: { "Content-Type": "text/html" }
+    }),
+    options.htmlContributions
+  );
+  return await transformedResponse.text();
+}
+export {
+  applyDocumentShellAttributeStamping,
+  composeDocumentShell,
+  composeSequentialLayoutChildren,
+  finalizeDocumentShellHtml,
+  renderPageDocumentShell
+};

package/src/route-renderer/orchestration/document-shell/layout-shell-props.service.d.ts

@@ -0,0 +1,20 @@
+import type { EcoPageLayoutEntry, LayoutPropsContext } from '../../../types/public-types.js';
+export type LayoutShellPropsContext = LayoutPropsContext & {
+    pageProps?: Record<string, unknown>;
+};
+/**
+ * Resolves the default shell props passed to a layout tier during route render.
+ */
+export declare function resolveLayoutShellProps(context: LayoutShellPropsContext): Record<string, unknown>;
+/**
+ * Resolves props for one layout entry, merging shell props with an optional factory.
+ */
+export declare function resolveLayoutEntryProps(entry: EcoPageLayoutEntry, context: LayoutShellPropsContext): Record<string, unknown>;
+/**
+ * Reads the normalized layout stack from a page component config.
+ */
+export declare function resolvePageLayoutComponents(layouts?: EcoPageLayoutEntry['component'][]): EcoPageLayoutEntry['component'][];
+/**
+ * Returns the innermost layout component from a normalized page layout stack.
+ */
+export declare function resolveInnermostPageLayout(layouts?: EcoPageLayoutEntry['component'][]): EcoPageLayoutEntry['component'] | undefined;

package/src/route-renderer/orchestration/document-shell/layout-shell-props.service.js

@@ -0,0 +1,31 @@
+function resolveLayoutShellProps(context) {
+  return context.locals ? { locals: context.locals } : {};
+}
+function resolveLayoutEntryProps(entry, context) {
+  const shellProps = resolveLayoutShellProps(context);
+  if (!entry.props) {
+    return shellProps;
+  }
+  const layoutPropsContext = {
+    params: context.params,
+    query: context.query,
+    locals: context.locals
+  };
+  return {
+    ...shellProps,
+    ...entry.props(layoutPropsContext)
+  };
+}
+function resolvePageLayoutComponents(layouts) {
+  return layouts && layouts.length > 0 ? layouts : [];
+}
+function resolveInnermostPageLayout(layouts) {
+  const stack = resolvePageLayoutComponents(layouts);
+  return stack[stack.length - 1];
+}
+export {
+  resolveInnermostPageLayout,
+  resolveLayoutEntryProps,
+  resolveLayoutShellProps,
+  resolvePageLayoutComponents
+};

package/src/route-renderer/orchestration/{component-render-context.d.ts → foreign-child/component-render-context.d.ts}

@@ -1,24 +1,17 @@
-import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoComponent } from '../../../types/public-types.js';
 /**
  * Result returned by a renderer-owned foreign-child runtime.
  *
- * `inline` keeps rendering inside the current integration. `resolved` returns a
- * renderer-owned value immediately, which can be final HTML or a renderer-local
- * transport token for later queue resolution.
+ * `inline` keeps rendering inside the current integration. `resolved.value` is
+ * the queue transport token string allocated by `createQueuedRuntime`; callers
+ * must not treat arbitrary objects as resolved output.
  */
 export type ForeignChildInterceptionResult = {
     kind: 'inline';
     props?: Record<string, unknown>;
 } | {
     kind: 'resolved';
-    value: unknown;
-};
-export type ForeignChildRenderInterception = {
-    kind: 'inline';
-    props?: Record<string, unknown>;
-} | {
-    kind: 'resolved';
-    value: unknown;
+    value: string;
 } | undefined;
 /**
  * Foreign-child metadata passed into the active renderer-owned runtime.
@@ -44,7 +37,7 @@ export interface ForeignChildRuntime {
      * which decides whether the child stays inline or leaves the current renderer.
      */
     interceptForeignChild?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult | Promise<ForeignChildInterceptionResult>;
-    interceptForeignChildSync?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult;
+    interceptForeignChildSync?(input: ForeignChildInterceptionInput): Exclude<ForeignChildInterceptionResult, undefined>;
 }
 type ForeignChildRenderInput = {
     component: EcoComponent;
@@ -58,7 +51,7 @@ type ForeignChildRenderInput = {
 export type ComponentRenderContext = {
     currentIntegration: string;
     foreignChildRuntime?: ForeignChildRuntime;
-    interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
+    interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildInterceptionResult> | ForeignChildInterceptionResult;
     finalizeComponentRender<T>(component: EcoComponent, content: T): T;
 };
 /**
@@ -72,7 +65,7 @@ export declare function getComponentRenderContext(): ComponentRenderContext | un
  *
  * The active runtime may resolve the foreign child immediately or keep it inline.
  */
-export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
+export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildInterceptionResult> | ForeignChildInterceptionResult;
 /**
  * Applies lazy trigger or injector wrapping to completed component output.
  *

package/src/route-renderer/orchestration/{component-render-context.js → foreign-child/component-render-context.js}

@@ -1,4 +1,4 @@
-import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./render-output.utils.js";
+import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./foreign-child-output.utils.js";
 class ComponentRenderOutputRuntime {
   finalizeComponentRender(component, content) {
     const lazyTriggers = component.config?._resolvedLazyTriggers;
@@ -51,7 +51,9 @@ class ContextualComponentRenderRuntime extends ComponentRenderOutputRuntime {
     const asyncInterception = this.context.foreignChildRuntime?.interceptForeignChild?.(foreignChildRuntimeInput);
     if (asyncInterception !== void 0) {
       if (isThenable(asyncInterception)) {
-        return asyncInterception.then((result) => this.applyForeignChildInterceptionResult(result));
+        return asyncInterception.then(
+          (result) => result === void 0 ? void 0 : this.applyForeignChildInterceptionResult(result)
+        );
       }
       return this.applyForeignChildInterceptionResult(asyncInterception);
     }

package/src/route-renderer/orchestration/{render-output.utils.d.ts → foreign-child/foreign-child-output.utils.d.ts}

@@ -1,4 +1,4 @@
-import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoComponent } from '../../../types/public-types.js';
 type ResolvedLazyScriptGroups = Readonly<NonNullable<EcoComponent['config']>['_resolvedLazyScripts']>;
 type TemplateContentShape = {
     strings: readonly string[];
@@ -21,6 +21,22 @@ type MarkupNodeLikeShape = {
  * @typeParam T Expected resolved type of the thenable.
  */
 export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;
+/** Returns whether a value looks like a DOM-like markup node from SSR integrations. */
+export declare function isMarkupNodeLike(value: unknown): value is MarkupNodeLikeShape;
+/**
+ * Returns whether a value is a plain opaque object that string serializers would
+ * coerce via `String(value)` rather than render as markup.
+ *
+ * @remarks
+ * Template results (`strings`/`values`), markup nodes, arrays, and framework
+ * element markers (`$$typeof`) are not opaque. Cross-integration children that
+ * are only plain objects must use EcoEmbed or already-serialized HTML.
+ */
+export declare function isOpaqueForeignChildValue(children: unknown): boolean;
+/**
+ * Throws when foreign-path children would be coerced from an opaque object.
+ */
+export declare function assertForeignChildrenNotOpaque(children: unknown, context: string): void;
 /**
  * Injects `data-eco-trigger` into the first real HTML element opening tag of
  * a component's rendered output string.
@@ -57,10 +73,4 @@ export declare function wrapWithScriptsInjector(content: string, lazyGroups: Res
 export declare function wrapWithScriptsInjector<T extends TemplateContentShape>(content: T, lazyGroups: ResolvedLazyScriptGroups): T | string;
 export declare function wrapWithScriptsInjector<T extends MarkupNodeLikeShape>(content: T, lazyGroups: ResolvedLazyScriptGroups): T;
 export declare function wrapWithScriptsInjector(content: unknown, lazyGroups: ResolvedLazyScriptGroups): string | TemplateContentShape | MarkupNodeLikeShape;
-export declare function decodeHtmlEntities(value: string): string;
-export declare function normalizeUnresolvedMarkerArtifactHtml(html: string): string;
-export declare function inspectUnresolvedMarkerArtifactHtml(html: string): {
-    hasUnresolvedMarkerArtifacts: boolean;
-    normalizedHtml: string;
-};
 export {};

package/src/route-renderer/orchestration/{render-output.utils.js → foreign-child/foreign-child-output.utils.js}

@@ -1,4 +1,4 @@
-import { buildInjectorMapScript } from "../../eco/lazy-injector-map.js";
+import { buildInjectorMapScript } from "../../../eco/lazy-injector-map.js";
 function cloneTemplateStrings(strings, firstString) {
   const nextStrings = [...strings];
   nextStrings[0] = firstString;
@@ -82,6 +82,37 @@ function isTemplateContentShape(value) {
 function isMarkupNodeLikeShape(value) {
   return typeof value === "object" && value !== null && typeof value.nodeType === "number";
 }
+function isMarkupNodeLike(value) {
+  return isMarkupNodeLikeShape(value);
+}
+function isOpaqueForeignChildValue(children) {
+  if (children === null || typeof children !== "object") {
+    return false;
+  }
+  if (Array.isArray(children)) {
+    return false;
+  }
+  if ("$$typeof" in children) {
+    return false;
+  }
+  if ("strings" in children && Array.isArray(children.strings)) {
+    return false;
+  }
+  if (isMarkupNodeLikeShape(children)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(children);
+  return prototype === Object.prototype || prototype === null;
+}
+function assertForeignChildrenNotOpaque(children, context) {
+  if (!isOpaqueForeignChildValue(children)) {
+    return;
+  }
+  const childTag = Object.prototype.toString.call(children);
+  throw new TypeError(
+    `[ecopages] ${context} refused to coerce opaque foreign children (${childTag}). Use EcoEmbed for cross-integration children or pass already-serialized HTML.`
+  );
+}
 function injectTriggerAttributeIntoString(content, triggerId) {
   const str = content;
   let i = 0;
@@ -139,33 +170,11 @@ function wrapWithScriptsInjector(content, lazyGroups) {
   }
   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,
+  assertForeignChildrenNotOpaque,
+  isMarkupNodeLike,
+  isOpaqueForeignChildValue,
   isThenable,
-  normalizeUnresolvedMarkerArtifactHtml,
   wrapWithScriptsInjector
 };

package/src/route-renderer/orchestration/{foreign-subtree-execution.service.d.ts → foreign-child/foreign-subtree-execution.service.d.ts}

@@ -1,11 +1,36 @@
-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 { 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 type QueuedForeignChildDecisionInput = {
+    currentIntegration: string;
+    targetIntegration?: string;
+    component: EcoComponent;
+    props: Record<string, unknown>;
+};
+export type QueuedForeignSubtreeResolution = {
+    token: string;
+    component: EcoComponent;
+    props: Record<string, unknown>;
+    componentInstanceId: string;
+};
+/**
+ * Shared mutable state for one renderer-owned queued foreign-subtree runtime.
+ */
+export type QueuedForeignSubtreeResolutionContext = {
+    rendererCache: Map<string, unknown>;
+    componentInstanceScope?: string;
+    nextForeignSubtreeId: number;
+    queuedResolutions: QueuedForeignSubtreeResolution[];
+};
+type QueuedForeignSubtreeIntegrationContext = BaseIntegrationContext & Record<string, unknown>;
+type QueuedForeignSubtreeChildRenderResult = {
+    assets: ProcessedAsset[];
+    html?: string;
+    children?: unknown;
+};
 export interface ForeignSubtreeExecutionOwningRenderer {
     readonly name: string;
     renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-    renderForeignSubtree(input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload>;
 }
 export interface ForeignSubtreeExecutionDecisionInput {
     currentIntegration: string;
@@ -21,7 +46,7 @@ export interface ForeignSubtreeExecutionRenderOptions {
         renderInput: ComponentRenderInput;
         rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>;
     }): ForeignChildRuntime;
-    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): Promise<ForeignSubtreeExecutionOwningRenderer>;
 }
 export interface ForeignSubtreeQueuedRuntimeOptions<TContext extends QueuedForeignSubtreeResolutionContext> {
     renderInput: ComponentRenderInput;
@@ -36,7 +61,7 @@ export interface ForeignSubtreeStringQueuedHtmlOptions {
     html: string;
     runtimeContextKey: string;
     queueLabel: string;
-    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): Promise<ForeignSubtreeExecutionOwningRenderer>;
     applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
     dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
 }
@@ -50,38 +75,45 @@ export interface ForeignSubtreeQueuedHtmlOptions<TContext extends QueuedForeignS
         children?: unknown;
         html?: string;
     }>;
-    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): Promise<ForeignSubtreeExecutionOwningRenderer>;
     applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
     dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
 }
+export interface ResolveQueuedForeignSubtreeTokensOptions<TContext extends QueuedForeignSubtreeResolutionContext> {
+    html: string;
+    runtimeContext?: TContext;
+    queueLabel: string;
+    renderQueuedChildren: (children: unknown, runtimeContext: TContext, queuedResolutionsByToken: Map<string, QueuedForeignSubtreeResolution>, resolveToken: (token: string) => Promise<string>) => Promise<QueuedForeignSubtreeChildRenderResult>;
+    resolveForeignSubtree: (input: ComponentRenderInput, rendererCache: Map<string, unknown>) => Promise<ForeignSubtreeRenderPayload | undefined>;
+    applyAttributesToFirstElement: (html: string, attributes: Record<string, string>) => string;
+    dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[];
+}
+/**
+ * Maps one component render result into the foreign-subtree payload shape used by
+ * queue resolution and integration tests.
+ */
+export declare function toForeignSubtreeRenderPayload(result: ComponentRenderResult): ForeignSubtreeRenderPayload;
 /**
  * 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.
+ * This service owns mixed-integration execution policy and the queued token
+ * mechanics renderers use when foreign children cannot resolve inline.
  */
 export declare class ForeignSubtreeExecutionService {
-    private readonly queuedForeignSubtreeResolutionService;
-    constructor(queuedForeignSubtreeResolutionService?: QueuedForeignSubtreeResolutionService);
     private requiresForeignChildRuntime;
-    /**
-     * 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.
-     */
+    createQueueRuntime<TContext extends QueuedForeignSubtreeResolutionContext>(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, unknown>;
+        runtimeContextKey: string;
+        tokenPrefix: string;
+        shouldQueueForeignChild: (input: QueuedForeignChildDecisionInput) => boolean;
+        createRuntimeContext?: (integrationContext: QueuedForeignSubtreeIntegrationContext, rendererCache: Map<string, unknown>) => TContext;
+    }): ForeignChildRuntime;
+    getRuntimeContext<TContext extends QueuedForeignSubtreeResolutionContext>(input: ComponentRenderInput, runtimeContextKey: string): TContext | undefined;
     resolveStringQueuedHtml<TContext extends QueuedForeignSubtreeResolutionContext>(options: ForeignSubtreeStringQueuedHtmlOptions): Promise<{
         assets: ProcessedAsset[];
         html: string;
@@ -90,21 +122,19 @@ export declare class ForeignSubtreeExecutionService {
         assets: ProcessedAsset[];
         html: string;
     }>;
-    /**
-     * Executes one component render with Foreign Child support under the current integration.
-     */
+    resolveQueuedForeignSubtreeTokens<TContext extends QueuedForeignSubtreeResolutionContext>(options: ResolveQueuedForeignSubtreeTokensOptions<TContext>): Promise<{
+        assets: ProcessedAsset[];
+        html: string;
+    }>;
     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>;
+    private createForeignSubtreeToken;
+    private ensureRuntimeContext;
 }
+export {};