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

package/src/route-renderer/README.md

@@ -16,18 +16,34 @@ The route renderer layer is responsible for:
 
 The architecture is organized around three distinct concepts:
 
-- `ownership`: preparation-time metadata that describes which integration owns each declared component edge
+- `ownership`: declared component dependency metadata validated before render
 - `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
 
 These concepts intentionally live in different places:
 
-- `ownership-planning.service.ts` builds `ownershipPlan`
-- `ownership-validation.service.ts` validates declared foreign ownership up front
+- `ownership-validation.service.ts` validates declared foreign ownership up front and fails the render on misconfiguration
 - `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
+- `foreign-subtree-execution.service.ts` owns mixed-integration execution policy and queued token resolution
+- `document-shell-render.service.ts` composes page, layout, and html template shells with one execution-scoped renderer cache
+- `integration-renderer.ts` owns renderer-to-renderer delegation and integration-specific render hooks
+- `route-render-orchestrator.ts` owns route preparation, final response capture, and unresolved artifact enforcement
+
+## Build-Time JSX vs Runtime Foreign Children
+
+Mixed-integration apps use two separate mechanisms:
+
+| Layer   | Mechanism                                                         | Purpose                                                                                                                                        |
+| ------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Build   | `getJsxOwnershipPlugins()` / `getHostScopedJsxOwnershipPlugins()` | Prepend `@jsxImportSource` so bundled `.tsx` files compile with the correct JSX runtime                                                        |
+| Build   | component identity source transform                               | After a lexical `eco.` gate, uses Oxc to wrap native factory options with `bindComponentIdentity()` and prepends the owning integration pragma |
+| Runtime | `eco.component()` / `eco.embed()` + foreign-child runtime         | Hand off cross-integration children during SSR                                                                                                 |
+
+See [`../build/README.md`](../build/README.md) for the JSX ownership helper split.
+
+## Document shell composition
+
+`composeDocumentShell` in core is the single string-shell primitive for wrapping a primary component with optional layout tiers and an Html template. Integrations may supply an optional `composeChildren` hook to replace sequential string wrapping with a unified tree (for example React element children) while still delegating foreign subtrees through `renderComponentWithForeignChildren`.
 
 ## Main Files
 
@@ -38,13 +54,26 @@ These concepts intentionally live in different places:
 
 ### `orchestration/`
 
-- `route-render-flow.ts`: one route render from page-module loading through final HTML output
+Root renderer classes:
+
 - `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
+- `string-markup-renderer.ts`: shared base for string-markup integrations
+
+Domain folders:
+
+- `ownership-graph/`: component graph walk/collect and up-front ownership validation
+- `foreign-child/`: active render context, foreign-subtree execution, deferred template serialization
+- `document-shell/`: shared page/layout/html shell composition and attribute stamping helpers
+- `route-pipeline/`: route preparation, final HTML capture, marker-artifact enforcement
+- `page-browser-graph/`: browser asset graph build, session cache, and injector assets
+
+**Page Browser Graph session behavior:**
+
+- In development, each Page Browser Graph is built on first request, cached in `page-browser-graph-session` with generation-safe commits, and invalidated when a tracked dependency changes. The per-route fast path is disabled while HMR is enabled so prop-dependent `dependencies(props)` cannot reuse the wrong graph. Hosts call `prepareHmrFileChange()` before HMR dispatch and defer client broadcasts when no browser subscribers are connected.
+- Dev SSR prewarm schedules processor-declared pathnames for background rendering. Static pages cache in watch mode when their Cache Strategy allows it; dynamic pages are never retained. The watcher invalidates HTML through `invalidateAppPageCacheBySourcePaths` when a registered source dependency changes, and falls back to global cache clear for categories whose route impact cannot be narrowed.
+- **Measuring dev page load:** set `ECOPAGES_REQUEST_PIPELINE_METRICS=1` and run `pnpm run test:bench:docs`. Compare cold vs warm navigations and phase totals from the benchmark output.
+- Production static export prebuilds browser graphs from the finalized route list into the in-memory `page-browser-graph-session` via `production-page-browser-graph-prebuild.ts`. Failed exports clear staged production session records so retries cannot reuse partial graph output.
+- Integrations activate lazily on first render or graph prebuild via `ensureIntegrationRuntimeReady()`. Processors initialize their small virtual modules during `setupAppRuntimePlugins()`; content collection server artifacts are built lazily when a server build first resolves the collection.
 
 ### `page-loading/`
 
@@ -56,63 +85,55 @@ These concepts intentionally live in different places:
 The route-render contract is:
 
 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.
+2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderOrchestrator`.
+3. `RouteRenderOrchestrator.prepareRenderOptions()` loads the page module, validates ownership (fail-fast), resolves final page props, resolves dependencies, and builds the page browser graph. Graph cache identity includes route params and query; contribution collection receives those same final props.
 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.
+6. `RouteRenderOrchestrator.executePrepared()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps document attributes when needed, and runs the HTML transformer.
 
 Important:
 
 - route-level fallback resolution is gone; unresolved artifacts are now a hard failure
-- ownership is declared from component metadata, not inferred from final HTML
+- ownership is declared from canonical component identity, not inferred from final HTML
+- declared page dependencies are resolved from final render inputs and carried to the owning integration; integrations may use them for renderer-specific lifecycle work such as HMR ownership
 - same-integration children stay renderer-local and do not need to pass through a universal transport
 
 ## Declared Foreign Child Contract
 
 Mixed-integration component configs must declare every possible foreign child in `config.dependencies.components`.
 
-That declaration is used for two things:
-
-- `OwnershipValidationService` surfaces missing metadata or unknown integrations before render execution
-- `OwnershipPlanningService` records the expected ownership shape in `ownershipPlan`
+`OwnershipValidationService` surfaces missing metadata or unknown integrations during `prepareRenderOptions()` and throws before render execution starts.
 
 At runtime, renderers still discover actual foreign children through the active component render context.
 
 ## Foreign Subtree Contract
 
-`renderForeignSubtree()` is the compatibility contract for renderer-to-renderer handoff. It returns:
-
-- `html`
-- `assets`
-- `rootTag`
-- optional `rootAttributes`
-- `attachmentPolicy`
-- `integrationName`
-
-`renderComponentWithForeignChildren()` is the higher-level renderer entrypoint. It is responsible for:
+`renderComponentWithForeignChildren()` is the renderer entrypoint for mixed-integration trees. It is responsible for:
 
 - 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
 
+Queue resolution maps owning-renderer output into the foreign-subtree payload shape via `toForeignSubtreeRenderPayload()` inside `foreign-subtree-execution.service.ts`.
+
 ## Queue Model
 
 Not every integration needs queue-based handoff.
 
 - 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.
+- Queue mechanics live inside `ForeignSubtreeExecutionService`; they are renderer-owned transport inside one render pass, not a general route-level fallback mechanism.
 
 ## React Island Notes
 
 - 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 React integration attaches island host attributes (`data-eco-island`, `data-eco-component-id`, `data-eco-component-key`, `data-eco-props`) to the SSR root when a single root exists.
+- Other integrations call `finalizeIslandComponentRender()` from core when a component instance ships client scripts. See `packages/core/src/islands/README.md`.
 - The island bootstrap mounts with `createRoot()` into that SSR root.
 - Hydration bootstraps listen for `eco:after-swap` so islands hydrate after client-side navigation.
 
 ## Current Limits
 
-- `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.
+- `integration-renderer.ts` remains the largest integration hook surface even after document-shell extraction.

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

@@ -0,0 +1,107 @@
+import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../../types/public-types.js';
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import { HtmlTransformerService, type HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+export type DocumentShellLayoutInput = {
+    component: EcoComponent;
+    props?: Record<string, unknown>;
+};
+export type DocumentShellComposeChildrenContext = {
+    primaryComponent: EcoComponent;
+    primaryProps: Record<string, unknown>;
+    primaryRender?: ComponentRenderResult;
+    layouts: DocumentShellLayoutInput[];
+    rendererCache: BaseIntegrationContext['rendererCache'];
+    renderComponentWithForeignChildren: DocumentShellRenderDependencies['renderComponentWithForeignChildren'];
+};
+export type DocumentShellComposeChildrenResult = {
+    /** Serialized or element children passed to the HTML template shell. */
+    children: unknown;
+    layoutRenders: ComponentRenderResult[];
+    /**
+     * Primary/page render assets when the hook performs unified composition.
+     *
+     * @remarks
+     * Omit only when the default sequential string path runs (core renders primary first).
+     */
+    primaryRender?: ComponentRenderResult;
+};
+/**
+ * Optional hook that replaces default sequential string layout wrapping.
+ *
+ * @remarks
+ * When provided, core skips the initial primary render and expects the hook to return
+ * `children` for the HTML template. Supply `primaryRender` so dependency assets still merge.
+ */
+export type DocumentShellComposeChildrenHook = (context: DocumentShellComposeChildrenContext) => Promise<DocumentShellComposeChildrenResult>;
+export type DocumentShellComposeInput = {
+    primaryComponent: EcoComponent;
+    primaryProps: Record<string, unknown>;
+    layout?: DocumentShellLayoutInput;
+    layouts?: DocumentShellLayoutInput[];
+    composeChildren?: DocumentShellComposeChildrenHook;
+    htmlTemplate: EcoComponent;
+    documentProps: Record<string, unknown>;
+};
+export type DocumentShellPageRenderInput = {
+    page: {
+        component: EcoComponent;
+        props: Record<string, unknown>;
+    };
+    layout?: DocumentShellLayoutInput;
+    layouts?: DocumentShellLayoutInput[];
+    composeChildren?: DocumentShellComposeChildrenHook;
+    htmlTemplate: EcoComponent;
+    metadata: PageMetadataProps;
+    pageProps: Record<string, unknown>;
+    documentProps?: Record<string, unknown>;
+    transformDocumentHtml?: (html: string) => string;
+};
+export type DocumentShellRenderDependencies = {
+    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+};
+export type DocumentShellAttributeStamping = {
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+};
+/**
+ * Default sequential string-child composition for document shell layers.
+ */
+export declare function composeSequentialLayoutChildren(context: DocumentShellComposeChildrenContext): Promise<DocumentShellComposeChildrenResult>;
+/**
+ * Composes page or view content through optional layout and document shells.
+ *
+ * One execution-scoped renderer cache is threaded through every shell layer so
+ * repeated foreign delegation reuses initialized renderers within one render pass.
+ */
+export declare function composeDocumentShell(dependencies: DocumentShellRenderDependencies, input: DocumentShellComposeInput): Promise<{
+    documentHtml: string;
+}>;
+/**
+ * Applies optional component-root and document-root attribute stamping before HTML
+ * transformation runs on explicit renderer-owned paths.
+ */
+export declare function applyDocumentShellAttributeStamping(html: string, stamping: DocumentShellAttributeStamping, options: {
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+}): string;
+/**
+ * Builds the final serialized document HTML for one route page render.
+ */
+export declare function renderPageDocumentShell(dependencies: DocumentShellRenderDependencies, input: DocumentShellPageRenderInput, docType: string): Promise<string>;
+/**
+ * Finalizes already-resolved HTML for explicit renderer-owned paths.
+ *
+ * @remarks
+ * Callers append renderer bootstrap dependencies before invoking this helper.
+ * Stamps document/root attributes and runs HTML transformation after nested
+ * foreign-subtree resolution without routing back through shared route execution.
+ */
+export declare function finalizeDocumentShellHtml(htmlTransformer: HtmlTransformerService, options: {
+    html: string;
+    partial?: boolean;
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+    transformHtml?: boolean;
+    htmlContributions?: HtmlDocumentContribution[];
+}): Promise<string>;

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

@@ -0,0 +1,155 @@
+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?.identity?.integration ?? 'ecopages';
+}
+/**
+ * Default sequential string-child composition for document shell layers.
+ */
+export 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,
+    };
+}
+/**
+ * Composes page or view content through optional layout and document shells.
+ *
+ * One execution-scoped renderer cache is threaded through every shell layer so
+ * repeated foreign delegation reuses initialized renderers within one render pass.
+ */
+export async function composeDocumentShell(dependencies, input) {
+    const rendererCache = new Map();
+    const layouts = resolveDocumentShellLayouts(input);
+    const composeChildren = input.composeChildren ?? composeSequentialLayoutChildren;
+    const usesCustomComposeChildren = input.composeChildren !== undefined;
+    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,
+    };
+}
+/**
+ * Applies optional component-root and document-root attribute stamping before HTML
+ * transformation runs on explicit renderer-owned paths.
+ */
+export 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;
+}
+/**
+ * Builds the final serialized document HTML for one route page render.
+ */
+export 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}`;
+}
+/**
+ * Finalizes already-resolved HTML for explicit renderer-owned paths.
+ *
+ * @remarks
+ * Callers append renderer bootstrap dependencies before invoking this helper.
+ * Stamps document/root attributes and runs HTML transformation after nested
+ * foreign-subtree resolution without routing back through shared route execution.
+ */
+export 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();
+}

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,37 @@
+/**
+ * Resolves the default shell props passed to a layout tier during route render.
+ */
+export function resolveLayoutShellProps(context) {
+    return context.locals ? { locals: context.locals } : {};
+}
+/**
+ * Resolves props for one layout entry, merging shell props with an optional factory.
+ */
+export 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),
+    };
+}
+/**
+ * Reads the normalized layout stack from a page component config.
+ */
+export function resolvePageLayoutComponents(layouts) {
+    return layouts && layouts.length > 0 ? layouts : [];
+}
+/**
+ * Returns the innermost layout component from a normalized page layout stack.
+ */
+export function resolveInnermostPageLayout(layouts) {
+    const stack = resolvePageLayoutComponents(layouts);
+    return stack[stack.length - 1];
+}

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.
  *