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

package/src/route-renderer/README.md

@@ -6,130 +6,113 @@ This folder contains the core rendering orchestration for Ecopages.
 
 The route renderer layer is responsible for:
 
-- Selecting the correct integration renderer for a route.
-- Loading page modules and resolving static data/metadata.
-- Resolving and processing component dependencies.
-- Applying full orchestration.
-- Emitting final HTML body output plus metadata/cache strategy.
+- selecting the correct integration renderer for a route
+- loading page modules and resolving static data or metadata
+- resolving component dependencies and page browser assets
+- coordinating mixed-integration rendering
+- emitting final HTML plus cache strategy
 
-## Main Components
+## Core Concepts
 
-### `route-renderer.ts`
-
-- `RouteRendererFactory` chooses integration renderers based on route file extension.
-- `RouteRenderer` delegates route execution to the selected integration renderer.
-
-### `integration-renderer.ts`
-
-Abstract base class that coordinates end-to-end route rendering:
-
-1. Resolve page module and page data.
-2. Resolve and process component dependencies.
-3. Add route-level assets and orchestration assets.
-4. Render HTML via integration-specific `render()`.
-5. Inject processed assets into final HTML through `HtmlTransformerService`.
-
-It also provides:
+The architecture is organized around three distinct concepts:
 
-- `renderToResponse()` contract for explicit-route rendering.
-- `renderComponent()` contract for component-level orchestration and artifact reporting.
-- marker graph resolution for nested cross-integration component boundaries.
+- `ownership`: preparation-time metadata that describes which integration owns each declared component edge
+- `foreign child`: a component encountered during render whose owning integration differs from the current integration
+- `foreign subtree`: the resolved HTML, assets, and root-attachment metadata returned by the owning renderer for that foreign child
 
-### `component-marker.ts`
+These concepts intentionally live in different places:
 
-Defines marker token contract for component-level orchestration:
+- `ownership-planning.service.ts` builds `ownershipPlan`
+- `ownership-validation.service.ts` validates declared foreign ownership up front
+- `component-render-context.ts` intercepts foreign children during active component render
+- `queued-foreign-subtree-resolution.service.ts` resolves queued foreign subtrees for renderers that cannot hand them off inline
+- `integration-renderer.ts` owns renderer-to-renderer delegation and shared shell composition
+- `route-render-flow.ts` owns route preparation, final response capture, and unresolved artifact enforcement
 
-- `createComponentMarker()` for canonical `<eco-marker ...></eco-marker>` generation.
-- `parseComponentMarkers()` for marker extraction from rendered HTML.
+## Main Files
 
-### `component-graph.ts`
+### `route-renderer.ts`
 
-Builds a deterministic DAG from marker nodes:
+- `RouteRendererFactory` chooses integration renderers from route files
+- `RouteRenderer` delegates execution to the selected renderer
 
-- node collection by marker id.
-- parent/child edges from slot reference registry.
-- topological levels for bottom-up execution.
+### `orchestration/`
 
-### `component-graph-executor.ts`
+- `route-render-flow.ts`: one route render from page-module loading through final HTML output
+- `integration-renderer.ts`: abstract base class for route rendering, explicit view rendering, and foreign-child delegation
+- `ownership-planning.service.ts`: declared ownership graph construction
+- `ownership-validation.service.ts`: up-front ownership validation for route roots and declared descendants
+- `component-render-context.ts`: active render context used by `eco.component()` to intercept foreign children
+- `queued-foreign-subtree-resolution.service.ts`: queue resolution for renderers that need token-based foreign-subtree handoff
+- `render-output.utils.ts`: unresolved artifact normalization and marker inspection
 
-Resolves graph levels in reverse order (leaf to root) and replaces markers with rendered HTML via integration `renderComponent()`.
+### `page-loading/`
 
-### `page-module-loader.ts`
+- `page-module-loader.ts`: imports page modules and normalizes page exports
+- `dependency-resolver.ts`: resolves component dependencies and browser-facing assets
 
-Service for loading page modules and deriving page data:
+## Render Flow
 
-- `importPageFile()` runtime-aware loading.
-- `resolvePageModule()` normalizes exports and statics.
-- `resolvePageData()` resolves static props then metadata.
+The route-render contract is:
 
-### `dependency-resolver.ts`
+1. `RouteRendererFactory` selects the owning integration renderer.
+2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderFlow`.
+3. `RouteRenderFlow.prepareRenderOptions()` loads the page module, validates ownership, builds `ownershipPlan`, resolves page data, resolves dependencies, and builds the page browser graph.
+4. The integration renderer performs page, layout, and document-shell rendering. When it encounters a foreign child, it delegates that child back to the owning renderer.
+5. If a renderer needs queued handoff, it emits internal foreign-subtree tokens and resolves them before returning final HTML.
+6. `RouteRenderFlow.execute()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps root or document attributes when needed, and runs the HTML transformer.
 
-Builds processed assets from component dependency declarations:
+Important:
 
-- Scripts/styles/components/modules.
-- Lazy dependency grouping and trigger derivation.
-- Default global injector behavior with optional legacy scripts-injector compatibility.
+- route-level fallback resolution is gone; unresolved artifacts are now a hard failure
+- ownership is declared from component metadata, not inferred from final HTML
+- same-integration children stay renderer-local and do not need to pass through a universal transport
 
-## Rendering Behavior
+## Declared Foreign Child Contract
 
-Default behavior:
+Mixed-integration component configs must declare every possible foreign child in `config.dependencies.components`.
 
-- marker-graph component orchestration + component render artifacts.
-- global lazy trigger map + global injector bootstrap.
+That declaration is used for two things:
 
-Global injector lifecycle notes:
+- `OwnershipValidationService` surfaces missing metadata or unknown integrations before render execution
+- `OwnershipPlanningService` records the expected ownership shape in `ownershipPlan`
 
-- The bootstrap remains active across client-side navigations.
-- On `eco:after-swap`, it prunes stale `ecopages/global-injector-map` scripts and calls `refresh()` so newly swapped `data-eco-trigger` elements can bind their lazy rules.
-- It must not call injector `cleanup()` on every swap, because that permanently disables future refresh work for the current runtime instance.
+At runtime, renderers still discover actual foreign children through the active component render context.
 
-## Current Component Artifact Contract
+## Foreign Subtree Contract
 
-Integration `renderComponent()` returns `ComponentRenderResult` with:
+`renderForeignSubtree()` is the compatibility contract for renderer-to-renderer handoff. It returns:
 
 - `html`
-- `canAttachAttributes`
+- `assets`
 - `rootTag`
-- `integrationName`
 - optional `rootAttributes`
-- optional `assets`
-
-Current base orchestration behavior:
-
-- Calls `renderComponent()` for the page root component.
-- Merges returned `assets` into processed dependencies.
-- Applies returned `rootAttributes` to the first element under `<body>`.
+- `attachmentPolicy`
+- `integrationName`
 
-When rendered output contains `eco-marker` nodes:
+`renderComponentWithForeignChildren()` is the higher-level renderer entrypoint. It is responsible for:
 
-- builds marker graph using `componentGraphContext` (`propsByRef`, `slotChildrenByRef`) from integration-specific page module exports.
-- resolves markers bottom-up through integration-specific `renderComponent()` calls.
-- fails fast when marker component refs or props refs are missing.
-- merges marker-rendered assets back into the dependency pipeline with deduplication.
+- reusing the execution-scoped owning-renderer cache
+- deciding whether the current component can stay local
+- creating a foreign-child runtime when nested foreign ownership must be resolved
+- normalizing unresolved artifact HTML before the render leaves the renderer
 
-This enables island-style hydration assets (for example React/Lit/Kita integration outputs) to be emitted through the normal dependency injection pipeline.
+## Queue Model
 
-## React Island Boundary Notes
+Not every integration needs queue-based handoff.
 
-- React component-level islands are emitted without synthetic wrapper elements.
-- The React integration attaches `data-eco-component-id` on the component's own SSR root element when a single root is available.
-- Island client bootstrap mounts with `createRoot()` into that root boundary.
-- The emitted hydration bootstrap also listens for `eco:after-swap` so islands hydrate correctly when their SSR markup appears after client-side navigation.
-- React hydration bootstraps are emitted with `data-eco-rerun` and stable `data-eco-script-id` metadata so head-script reconciliation can safely re-execute them when needed.
-- This keeps authored DOM shape stable for global layout/style selectors while preserving per-island runtime isolation.
+- If a renderer can resolve a foreign child inline, it returns resolved output immediately.
+- If it cannot, it may emit internal foreign-subtree tokens and resolve them before returning final HTML.
+- The queue service is only for renderer-owned transport inside one render pass. It is not a general route-level fallback mechanism.
 
-## Output Pipeline (High-Level)
+## React Island Notes
 
-1. Factory selects integration renderer.
-2. Integration renderer prepares render options.
-3. Dependencies are resolved and processed.
-4. Orchestration assets/artifacts are merged.
-5. Integration renderer generates HTML body.
-6. HTML transformer injects head/body dependencies.
-7. Route result returns body + metadata + cache strategy.
+- React islands are emitted without synthetic wrapper elements.
+- The React integration attaches `data-eco-component-id` to the SSR root when a single root exists.
+- The island bootstrap mounts with `createRoot()` into that SSR root.
+- Hydration bootstraps listen for `eco:after-swap` so islands hydrate after client-side navigation.
 
-## Notes for Future Work
+## Current Limits
 
-- Expand integration-side marker emission so more nested trees are resolved through graph mode by default.
-- Add broader fixtures/e2e for deep multi-level slot graphs.
-- Add optional batching by integration per graph level to reduce repeated renderer invocations.
+- `ownershipPlan` is still diagnostic and preparatory metadata; it does not yet drive a full route-composer execution model.
+- Different integrations still own different foreign-child runtime strategies, which is intentional where child transport or hydration behavior differs.

package/src/route-renderer/orchestration/component-render-context.d.ts

@@ -0,0 +1,89 @@
+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.
+ */
+export type ForeignChildInterceptionResult = {
+    kind: 'inline';
+} | {
+    kind: 'resolved';
+    value: unknown;
+};
+/**
+ * Foreign-child metadata passed into the active renderer-owned runtime.
+ */
+export type ForeignChildInterceptionInput = {
+    currentIntegration: string;
+    targetIntegration?: string;
+    component: EcoComponent;
+    props: Record<string, unknown>;
+};
+/**
+ * Narrow renderer-owned foreign-child runtime injected into one active render
+ * context.
+ *
+ * Integrations implement this contract when foreign children must be handed
+ * off inside the renderer instead of being left for route-level reconciliation.
+ */
+export interface ForeignChildRuntime {
+    /**
+     * Intercepts one foreign child during an active render.
+     *
+     * This runtime is typically installed by the Foreign Subtree execution module,
+     * which decides whether the child stays inline or leaves the current renderer.
+     */
+    interceptForeignChild?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult | Promise<ForeignChildInterceptionResult>;
+    interceptForeignChildSync?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult;
+}
+type ForeignChildRenderInput = {
+    component: EcoComponent;
+    props: Record<string, unknown>;
+    targetIntegration?: string;
+};
+/**
+ * Per-render mutable state used while applying foreign-child interception and lazy
+ * output wrapping.
+ */
+export type ComponentRenderContext = {
+    currentIntegration: string;
+    foreignChildRuntime?: ForeignChildRuntime;
+    interceptForeignChild(input: ForeignChildRenderInput): Promise<unknown | undefined> | unknown | undefined;
+    finalizeComponentRender<T>(component: EcoComponent, content: T): T;
+};
+/**
+ * Returns the current component render context, if one is active.
+ *
+ * @returns Active render context or `undefined` outside render execution.
+ */
+export declare function getComponentRenderContext(): ComponentRenderContext | undefined;
+/**
+ * Runs foreign-child interception for one component render step.
+ *
+ * The active runtime may resolve the foreign child immediately or keep it inline.
+ */
+export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<unknown | undefined> | unknown | undefined;
+/**
+ * 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 declare function finalizeComponentRender<T>(component: EcoComponent, content: T): T;
+/**
+ * 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 declare function runWithComponentRenderContext<T>(input: {
+    currentIntegration: string;
+    foreignChildRuntime?: ForeignChildRuntime;
+}, render: () => Promise<T>): Promise<{
+    value: T;
+}>;
+export {};

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