@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

package/src/route-renderer/orchestration/foreign-child/foreign-child-output.utils.js

@@ -0,0 +1,195 @@
+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);
+            let nameEnd = tagSlice.search(/[\s/>]/);
+            if (nameEnd === -1) {
+                if (!/^[a-zA-Z][\w:-]*$/.test(tagSlice)) {
+                    break;
+                }
+                nameEnd = tagSlice.length;
+            }
+            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 {};