@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

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

@@ -0,0 +1,196 @@
+import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from './foreign-child-output.utils.js';
+/**
+ * Shared output finalization behavior used both inside and outside active render contexts.
+ *
+ * This stage is responsible only for lazy trigger or injector wrapping. Foreign-child
+ * interception stays in `ContextualComponentRenderRuntime`.
+ */
+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);
+    }
+}
+/**
+ * Render-context-aware runtime that delegates foreign-child interception.
+ */
+class ContextualComponentRenderRuntime extends ComponentRenderOutputRuntime {
+    context;
+    constructor(context) {
+        super();
+        this.context = context;
+    }
+    applyForeignChildInterceptionResult(result) {
+        if (result.kind === 'resolved') {
+            return result;
+        }
+        return result.props ? result : undefined;
+    }
+    /**
+     * 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 !== undefined) {
+            if (isThenable(asyncInterception)) {
+                return asyncInterception.then((result) => result === undefined ? undefined : this.applyForeignChildInterceptionResult(result));
+            }
+            return this.applyForeignChildInterceptionResult(asyncInterception);
+        }
+        const syncInterception = this.context.foreignChildRuntime?.interceptForeignChildSync?.(foreignChildRuntimeInput);
+        if (syncInterception === undefined) {
+            return undefined;
+        }
+        return this.applyForeignChildInterceptionResult(syncInterception);
+    }
+}
+const GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY = '__ECOPAGES_COMPONENT_RENDER_CONTEXT_STATE__';
+/**
+ * Chooses the widest shared global scope available for process-wide state.
+ *
+ * `process` is preferred when present so duplicate bundles or module instances in
+ * the same runtime still converge on one shared context registry.
+ */
+function getSharedContextScope() {
+    const globalProcess = globalThis.process;
+    if (globalProcess && typeof globalProcess === 'object') {
+        return globalProcess;
+    }
+    return globalThis;
+}
+/**
+ * Returns the singleton mutable state used by component render contexts.
+ */
+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];
+}
+/**
+ * Lazily initializes async context storage for Node runtimes.
+ *
+ * Falls back to in-memory stack mode when async_hooks is unavailable.
+ *
+ * @returns Async context storage when available; otherwise `null`.
+ */
+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;
+}
+/**
+ * Returns the current component render context, if one is active.
+ *
+ * @returns Active render context or `undefined` outside render execution.
+ */
+export function getComponentRenderContext() {
+    const state = getComponentRenderContextState();
+    return state.nodeContextStorage?.getStore() ?? state.contextStack[state.contextStack.length - 1];
+}
+const componentRenderOutputRuntime = new ComponentRenderOutputRuntime();
+/**
+ * Runs foreign-child interception for one component render step.
+ *
+ * The active runtime may resolve the foreign child immediately or keep it inline.
+ */
+export function interceptForeignChild(input) {
+    return getComponentRenderContext()?.interceptForeignChild(input);
+}
+/**
+ * Applies lazy trigger or injector wrapping to completed component output.
+ *
+ * This helper works both inside render-context execution and in fallback flows
+ * where no active context exists.
+ */
+export function finalizeComponentRender(component, content) {
+    const renderContext = getComponentRenderContext();
+    return (renderContext?.finalizeComponentRender(component, content) ??
+        componentRenderOutputRuntime.finalizeComponentRender(component, content));
+}
+/**
+ * Runs render work under a fresh component render context and returns the
+ * resulting value.
+ *
+ * @param input Execution metadata for current integration and foreign-child policy.
+ * @param render Async render function to execute inside the context.
+ * @returns Render result value.
+ */
+export 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,
+    };
+}

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/foreign-child/foreign-child-output.utils.js

@@ -0,0 +1,191 @@
+import { buildInjectorMapScript } from '../../../eco/lazy-injector-map.js';
+function cloneTemplateStrings(strings, firstString) {
+    const nextStrings = [...strings];
+    nextStrings[0] = firstString;
+    const rawDescriptor = Object.getOwnPropertyDescriptor(strings, 'raw');
+    if (rawDescriptor && Array.isArray(rawDescriptor.value)) {
+        const rawStrings = [...rawDescriptor.value];
+        rawStrings[0] = firstString;
+        Object.defineProperty(nextStrings, 'raw', {
+            ...rawDescriptor,
+            value: rawStrings,
+        });
+    }
+    return nextStrings;
+}
+function cloneTemplateContentWithUpdatedFirstString(content, firstString) {
+    const descriptors = Object.getOwnPropertyDescriptors(content);
+    const clonedContent = Object.create(Object.getPrototypeOf(content));
+    const stringsDescriptor = descriptors.strings;
+    Object.defineProperties(clonedContent, {
+        ...descriptors,
+        strings: {
+            ...stringsDescriptor,
+            value: cloneTemplateStrings(content.strings, firstString),
+        },
+    });
+    return clonedContent;
+}
+function cloneMarkupNodeLikeWithUpdatedOuterHtml(content, outerHTML) {
+    const descriptors = Object.getOwnPropertyDescriptors(content);
+    const clonedContent = Object.create(Object.getPrototypeOf(content));
+    const outerHTMLDescriptor = descriptors.outerHTML;
+    Object.defineProperties(clonedContent, {
+        ...descriptors,
+        outerHTML: {
+            configurable: outerHTMLDescriptor?.configurable ?? true,
+            enumerable: outerHTMLDescriptor?.enumerable ?? true,
+            writable: true,
+            value: outerHTML,
+        },
+    });
+    return clonedContent;
+}
+function wrapWithScriptsInjectorMarkup(content, injectorMapScript) {
+    return `<scripts-injector><script type="ecopages/injector-map">${injectorMapScript}</script>${content}</scripts-injector>`;
+}
+function cloneTemplateContentWithWrappedInjector(content, injectorMapScript) {
+    if (content.strings.length === 0) {
+        return wrapWithScriptsInjectorMarkup(String(content), injectorMapScript);
+    }
+    const nextStrings = [...content.strings];
+    nextStrings[0] = wrapWithScriptsInjectorMarkup(nextStrings[0] ?? '', injectorMapScript);
+    nextStrings[nextStrings.length - 1] = `${nextStrings[nextStrings.length - 1] ?? ''}</scripts-injector>`;
+    const rawDescriptor = Object.getOwnPropertyDescriptor(content.strings, 'raw');
+    if (rawDescriptor && Array.isArray(rawDescriptor.value)) {
+        const rawStrings = [...rawDescriptor.value];
+        rawStrings[0] = wrapWithScriptsInjectorMarkup(rawStrings[0] ?? '', injectorMapScript);
+        rawStrings[rawStrings.length - 1] = `${rawStrings[rawStrings.length - 1] ?? ''}</scripts-injector>`;
+        Object.defineProperty(nextStrings, 'raw', {
+            ...rawDescriptor,
+            value: rawStrings,
+        });
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(content);
+    const clonedContent = Object.create(Object.getPrototypeOf(content));
+    const stringsDescriptor = descriptors.strings;
+    Object.defineProperties(clonedContent, {
+        ...descriptors,
+        strings: {
+            ...stringsDescriptor,
+            value: nextStrings,
+        },
+    });
+    return clonedContent;
+}
+/**
+ * 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 function isThenable(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'then' in value &&
+        typeof value.then === 'function');
+}
+function isTemplateContentShape(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        Array.isArray(value.strings) &&
+        ((value.values ?? undefined) === undefined ||
+            Array.isArray(value.values)));
+}
+function isMarkupNodeLikeShape(value) {
+    return (typeof value === 'object' && value !== null && typeof value.nodeType === 'number');
+}
+/** Returns whether a value looks like a DOM-like markup node from SSR integrations. */
+export function isMarkupNodeLike(value) {
+    return isMarkupNodeLikeShape(value);
+}
+/**
+ * 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 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;
+}
+/**
+ * Throws when foreign-path children would be coerced from an opaque object.
+ */
+export 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;
+    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;
+}
+export function addTriggerAttribute(content, triggerId) {
+    if (isTemplateContentShape(content)) {
+        if (content.strings.length === 0) {
+            return String(content);
+        }
+        return cloneTemplateContentWithUpdatedFirstString(content, injectTriggerAttributeIntoString(content.strings[0] ?? '', triggerId));
+    }
+    if (isMarkupNodeLikeShape(content) && typeof content.outerHTML === 'string') {
+        return cloneMarkupNodeLikeWithUpdatedOuterHtml(content, injectTriggerAttributeIntoString(content.outerHTML, triggerId));
+    }
+    return injectTriggerAttributeIntoString(String(content), triggerId);
+}
+export function wrapWithScriptsInjector(content, lazyGroups) {
+    const injectorMapScript = buildInjectorMapScript(lazyGroups ?? []);
+    if (isTemplateContentShape(content)) {
+        return cloneTemplateContentWithWrappedInjector(content, injectorMapScript);
+    }
+    if (isMarkupNodeLikeShape(content) && typeof content.outerHTML === 'string') {
+        return cloneMarkupNodeLikeWithUpdatedOuterHtml(content, wrapWithScriptsInjectorMarkup(content.outerHTML, injectorMapScript));
+    }
+    return wrapWithScriptsInjectorMarkup(String(content), injectorMapScript);
+}

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 {};