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

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

@@ -1,310 +0,0 @@
-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

@@ -1,310 +0,0 @@
-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'),
-	};
-}