@ecopages/core 0.2.0-alpha.52 → 0.2.0-alpha.54

package/src/route-renderer/orchestration/queued-foreign-subtree-resolution.service.ts

@@ -0,0 +1,310 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+import type {
+	BaseIntegrationContext,
+	ForeignSubtreeRenderPayload,
+	ComponentRenderInput,
+	EcoComponent,
+} from '../../types/public-types.ts';
+import type { ForeignChildRuntime } from './component-render-context.ts';
+
+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.
+ *
+ * Renderers that cannot resolve foreign children inline can enqueue transport
+ * tokens during their initial render, then resolve those tokens against the
+ * owning renderer before returning final HTML.
+ */
+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;
+};
+
+/**
+ * Lower-level queue orchestration for renderer-owned foreign-child runtimes that emit
+ * temporary transport tokens during one render pass.
+ *
+ * The service keeps three responsibilities in one place:
+ * - storing per-render queue state on the active integration context
+ * - creating a `ForeignChildRuntime` that enqueues foreign children
+ * - resolving queued tokens back through the owning renderer before final HTML
+ *   leaves the current renderer
+ *
+ * The deeper Foreign Subtree execution module composes this queue helper with
+ * renderer-cache delegation and active render-context execution. This service
+ * stays focused on queue bookkeeping, recursion, cycle detection, and asset merging.
+ */
+export class QueuedForeignSubtreeResolutionService {
+	/**
+	 * Reads the queued foreign-subtree runtime state previously attached to one render.
+	 */
+	getRuntimeContext<TContext extends QueuedForeignSubtreeResolutionContext>(
+		input: ComponentRenderInput,
+		runtimeContextKey: string,
+	): TContext | undefined {
+		const integrationContext = input.integrationContext as QueuedForeignSubtreeIntegrationContext | undefined;
+		const runtimeContext = integrationContext?.[runtimeContextKey];
+
+		if (typeof runtimeContext !== 'object' || runtimeContext === null) {
+			return undefined;
+		}
+
+		return runtimeContext as TContext;
+	}
+
+	/**
+	 * Creates the runtime hook used by `runWithComponentRenderContext()` for one
+	 * renderer-owned queue.
+	 *
+	 * When the renderer decides a foreign child must be handed off, the runtime returns
+	 * a resolved transport token instead of rendering the foreign component inline.
+	 */
+	createRuntime<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 {
+		const runtimeContext = this.ensureRuntimeContext(options);
+
+		const interceptForeignChild = (input: QueuedForeignChildDecisionInput) => {
+			if (!options.shouldQueueForeignChild(input)) {
+				return {
+					kind: 'inline' as const,
+					props: { ...input.props },
+				};
+			}
+
+			runtimeContext.nextForeignSubtreeId += 1;
+			const foreignSubtreeId = runtimeContext.nextForeignSubtreeId;
+			const token = this.createForeignSubtreeToken(options.tokenPrefix, runtimeContext, foreignSubtreeId);
+			runtimeContext.queuedResolutions.push({
+				token,
+				component: input.component,
+				props: { ...input.props },
+				componentInstanceId: runtimeContext.componentInstanceScope
+					? `${runtimeContext.componentInstanceScope}_n_${foreignSubtreeId}`
+					: `n_${foreignSubtreeId}`,
+			});
+
+			return {
+				kind: 'resolved' as const,
+				value: token,
+			};
+		};
+
+		return {
+			interceptForeignChild,
+			interceptForeignChildSync: interceptForeignChild,
+		};
+	}
+
+	/**
+	 * Resolves every queued transport token in one renderer-owned HTML fragment.
+	 *
+	 * The caller supplies framework-specific child rendering, while this service
+	 * handles recursive token replacement, cycle detection, root-attribute
+	 * application, and merged asset collection.
+	 */
+	async resolveQueuedHtml<TContext extends QueuedForeignSubtreeResolutionContext>(options: {
+		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[];
+	}): Promise<{ assets: ProcessedAsset[]; html: string }> {
+		if (!options.runtimeContext || options.runtimeContext.queuedResolutions.length === 0) {
+			return { assets: [], html: options.html };
+		}
+
+		const runtimeContext = options.runtimeContext;
+		const queuedResolutionsByToken = new Map<string, QueuedForeignSubtreeResolution>();
+		const resolvedHtmlByToken = new Map<string, string>();
+		const resolvingTokens = new Set<string>();
+		const collectedAssets: ProcessedAsset[] = [];
+
+		const syncQueuedResolutions = () => {
+			for (const resolution of runtimeContext.queuedResolutions) {
+				if (!queuedResolutionsByToken.has(resolution.token)) {
+					queuedResolutionsByToken.set(resolution.token, resolution);
+				}
+			}
+		};
+
+		const resolveToken = async (token: string): Promise<string> => {
+			syncQueuedResolutions();
+
+			const cachedHtml = resolvedHtmlByToken.get(token);
+			if (cachedHtml) {
+				return cachedHtml;
+			}
+
+			const resolution = queuedResolutionsByToken.get(token);
+			if (!resolution) {
+				return token;
+			}
+
+			if (resolvingTokens.has(token)) {
+				throw new Error(
+					`[ecopages] ${options.queueLabel} foreign-subtree queue contains a cycle or unresolved dependency links.`,
+				);
+			}
+
+			resolvingTokens.add(token);
+
+			try {
+				const renderedChildren = await options.renderQueuedChildren(
+					resolution.props.children,
+					runtimeContext,
+					queuedResolutionsByToken,
+					resolveToken,
+				);
+				syncQueuedResolutions();
+
+				if (renderedChildren.assets.length > 0) {
+					collectedAssets.push(...renderedChildren.assets);
+				}
+
+				const foreignSubtreeRender = await options.resolveForeignSubtree(
+					{
+						component: resolution.component,
+						props: { ...resolution.props },
+						children: renderedChildren.html ?? renderedChildren.children,
+						integrationContext: {
+							rendererCache: runtimeContext.rendererCache,
+							componentInstanceId: resolution.componentInstanceId,
+						},
+					},
+					runtimeContext.rendererCache,
+				);
+
+				if (!foreignSubtreeRender) {
+					throw new Error(
+						`[ecopages] ${options.queueLabel} queued foreign subtree could not resolve its owning renderer.`,
+					);
+				}
+
+				if ((foreignSubtreeRender.assets?.length ?? 0) > 0) {
+					collectedAssets.push(...(foreignSubtreeRender.assets ?? []));
+				}
+
+				const resolvedHtml =
+					foreignSubtreeRender.attachmentPolicy.kind === 'first-element' &&
+					foreignSubtreeRender.rootAttributes
+						? options.applyAttributesToFirstElement(
+								foreignSubtreeRender.html,
+								foreignSubtreeRender.rootAttributes,
+							)
+						: foreignSubtreeRender.html;
+
+				resolvedHtmlByToken.set(token, resolvedHtml);
+				return resolvedHtml;
+			} finally {
+				resolvingTokens.delete(token);
+			}
+		};
+
+		let resolvedHtml = options.html;
+
+		for (let index = 0; index < runtimeContext.queuedResolutions.length; index += 1) {
+			syncQueuedResolutions();
+
+			const resolution = runtimeContext.queuedResolutions[index];
+			if (!resolvedHtml.includes(resolution.token)) {
+				continue;
+			}
+
+			resolvedHtml = resolvedHtml.split(resolution.token).join(await resolveToken(resolution.token));
+		}
+
+		return {
+			assets: options.dedupeProcessedAssets(collectedAssets),
+			html: resolvedHtml,
+		};
+	}
+
+	private createForeignSubtreeToken(
+		tokenPrefix: string,
+		runtimeContext: QueuedForeignSubtreeResolutionContext,
+		foreignSubtreeId: number,
+	): string {
+		return `${tokenPrefix}${runtimeContext.componentInstanceScope ?? 'root'}__${foreignSubtreeId}__`;
+	}
+
+	private ensureRuntimeContext<TContext extends QueuedForeignSubtreeResolutionContext>(options: {
+		renderInput: ComponentRenderInput;
+		rendererCache: Map<string, unknown>;
+		runtimeContextKey: string;
+		createRuntimeContext?: (
+			integrationContext: QueuedForeignSubtreeIntegrationContext,
+			rendererCache: Map<string, unknown>,
+		) => TContext;
+	}): TContext {
+		let integrationContext: QueuedForeignSubtreeIntegrationContext;
+		if (
+			typeof options.renderInput.integrationContext === 'object' &&
+			options.renderInput.integrationContext !== null
+		) {
+			integrationContext = options.renderInput.integrationContext as QueuedForeignSubtreeIntegrationContext;
+		} else {
+			integrationContext = {};
+		}
+
+		const existingRuntimeContext = integrationContext[options.runtimeContextKey];
+		if (typeof existingRuntimeContext !== 'object' || existingRuntimeContext === null) {
+			integrationContext[options.runtimeContextKey] =
+				options.createRuntimeContext?.(integrationContext, options.rendererCache) ??
+				({
+					rendererCache: options.rendererCache,
+					componentInstanceScope: integrationContext.componentInstanceId,
+					nextForeignSubtreeId: 0,
+					queuedResolutions: [],
+				} satisfies QueuedForeignSubtreeResolutionContext);
+		} else {
+			(existingRuntimeContext as QueuedForeignSubtreeResolutionContext).rendererCache = options.rendererCache;
+		}
+
+		integrationContext.rendererCache = options.rendererCache;
+		options.renderInput.integrationContext = integrationContext;
+
+		return integrationContext[options.runtimeContextKey] as TContext;
+	}
+}

package/src/route-renderer/orchestration/render-output.utils.ts

@@ -0,0 +1,310 @@
+import type { EcoComponent } from '../../types/public-types.ts';
+import { buildInjectorMapScript } from '../../eco/lazy-injector-map.ts';
+
+type ResolvedLazyScriptGroups = Readonly<NonNullable<EcoComponent['config']>['_resolvedLazyScripts']>;
+
+type TemplateContentShape = {
+	strings: readonly string[];
+	values?: readonly unknown[];
+	[key: string]: unknown;
+};
+
+type MarkupNodeLikeShape = {
+	nodeType: number;
+	outerHTML?: string;
+	childNodes?: readonly unknown[];
+	textContent?: string;
+	[key: string]: unknown;
+};
+
+function cloneTemplateStrings(strings: readonly string[], firstString: string): string[] {
+	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<T extends TemplateContentShape>(
+	content: T,
+	firstString: string,
+): T {
+	const descriptors = Object.getOwnPropertyDescriptors(content);
+	const clonedContent = Object.create(Object.getPrototypeOf(content)) as T;
+	const stringsDescriptor = descriptors.strings;
+
+	Object.defineProperties(clonedContent, {
+		...descriptors,
+		strings: {
+			...stringsDescriptor,
+			value: cloneTemplateStrings(content.strings, firstString),
+		},
+	});
+
+	return clonedContent;
+}
+
+function cloneMarkupNodeLikeWithUpdatedOuterHtml<T extends MarkupNodeLikeShape>(content: T, outerHTML: string): T {
+	const descriptors = Object.getOwnPropertyDescriptors(content);
+	const clonedContent = Object.create(Object.getPrototypeOf(content)) as T;
+	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: string, injectorMapScript: string): string {
+	return `<scripts-injector><script type="ecopages/injector-map">${injectorMapScript}</script>${content}</scripts-injector>`;
+}
+
+function cloneTemplateContentWithWrappedInjector<T extends TemplateContentShape>(
+	content: T,
+	injectorMapScript: string,
+): T | string {
+	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)) as T;
+	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<T>(value: unknown): value is PromiseLike<T> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		'then' in value &&
+		typeof (value as { then?: unknown }).then === 'function'
+	);
+}
+
+function isTemplateContentShape(value: unknown): value is TemplateContentShape {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		Array.isArray((value as { strings?: unknown }).strings) &&
+		(((value as { values?: unknown }).values ?? undefined) === undefined ||
+			Array.isArray((value as { values?: unknown }).values))
+	);
+}
+
+function isMarkupNodeLikeShape(value: unknown): value is MarkupNodeLikeShape {
+	return (
+		typeof value === 'object' && value !== null && typeof (value as { nodeType?: unknown }).nodeType === 'number'
+	);
+}
+
+function injectTriggerAttributeIntoString(content: string, triggerId: string): string {
+	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;
+}
+
+/**
+ * Injects `data-eco-trigger` into the first real HTML element opening tag of
+ * a component's rendered output string.
+ *
+ * The scan skips over leading whitespace, HTML comments (`<!-- -->`), CDATA
+ * sections, and doctype declarations so that the attribute is always placed on
+ * the first actual element — not spurious markup that can precede it.
+ *
+ * The insertion point is the end of the element's tag name, before any existing
+ * attributes or the closing `>`, which produces output like:
+ *
+ * ```html
+ * <my-element data-eco-trigger="eco-trigger-abc123" class="foo">…</my-element>
+ * ```
+ *
+ * When no eligible opening tag is found the original string is returned
+ * unchanged so callers never receive a broken fragment.
+ *
+ * @param content Rendered HTML string (or any value coercible to string).
+ * @param triggerId Stable trigger identifier produced by `buildResolvedLazyTriggers`.
+ */
+export function addTriggerAttribute(content: string, triggerId: string): string;
+export function addTriggerAttribute<T extends TemplateContentShape>(content: T, triggerId: string): T;
+export function addTriggerAttribute<T extends MarkupNodeLikeShape>(content: T, triggerId: string): T;
+export function addTriggerAttribute(
+	content: unknown,
+	triggerId: string,
+): string | TemplateContentShape | MarkupNodeLikeShape;
+export function addTriggerAttribute(
+	content: unknown,
+	triggerId: string,
+): string | TemplateContentShape | MarkupNodeLikeShape {
+	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);
+}
+
+/**
+ * Wraps rendered component output in a `<scripts-injector>` element that
+ * carries an inline injector map for the component's lazy script groups.
+ *
+ * @param content Rendered component HTML.
+ * @param lazyGroups Resolved lazy script groups attached to the component config.
+ */
+export function wrapWithScriptsInjector(content: string, lazyGroups: ResolvedLazyScriptGroups): string;
+export function wrapWithScriptsInjector<T extends TemplateContentShape>(
+	content: T,
+	lazyGroups: ResolvedLazyScriptGroups,
+): T | string;
+export function wrapWithScriptsInjector<T extends MarkupNodeLikeShape>(
+	content: T,
+	lazyGroups: ResolvedLazyScriptGroups,
+): T;
+export function wrapWithScriptsInjector(
+	content: unknown,
+	lazyGroups: ResolvedLazyScriptGroups,
+): string | TemplateContentShape | MarkupNodeLikeShape;
+export function wrapWithScriptsInjector(
+	content: unknown,
+	lazyGroups: ResolvedLazyScriptGroups,
+): string | TemplateContentShape | MarkupNodeLikeShape {
+	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);
+}
+
+export function decodeHtmlEntities(value: string): string {
+	let decoded = value;
+	let previous: string | undefined;
+
+	do {
+		previous = decoded;
+		decoded = decoded
+			.replaceAll('&quot;', '"')
+			.replaceAll('&#39;', "'")
+			.replaceAll('&#x27;', "'")
+			.replaceAll('&lt;', '<')
+			.replaceAll('&gt;', '>')
+			.replaceAll('&amp;', '&');
+	} while (decoded !== previous);
+
+	return decoded;
+}
+
+export function normalizeUnresolvedMarkerArtifactHtml(html: string): string {
+	return html.replace(
+		/&(?:amp;)?lt;eco-marker\b[\s\S]*?&(?:amp;)?gt;&(?:amp;)?lt;\/eco-marker&(?:amp;)?gt;/g,
+		(marker) => decodeHtmlEntities(marker),
+	);
+}
+
+export function inspectUnresolvedMarkerArtifactHtml(html: string): {
+	hasUnresolvedMarkerArtifacts: boolean;
+	normalizedHtml: string;
+} {
+	const normalizedHtml = normalizeUnresolvedMarkerArtifactHtml(html);
+
+	return {
+		normalizedHtml,
+		hasUnresolvedMarkerArtifacts: normalizedHtml.includes('<eco-marker'),
+	};
+}