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

package/src/route-renderer/orchestration/ownership-planning.service.ts

@@ -0,0 +1,97 @@
+import type {
+	OwnershipPlan,
+	OwnershipPlanNode,
+	OwnershipPlanNodeSource,
+	OwnershipValidationError,
+	EcoComponent,
+} from '../../types/public-types.ts';
+import { mapDeclaredOwnershipGraph } from './declared-ownership-graph.ts';
+
+type OwnershipPlanBuildInput = {
+	routeFile: string;
+	currentIntegrationName: string;
+	HtmlTemplate: EcoComponent;
+	Layout?: EcoComponent;
+	Page: EcoComponent;
+	validationErrors?: OwnershipValidationError[];
+};
+
+type OwnershipPlanBuildEntry = {
+	component: EcoComponent;
+	source: Extract<OwnershipPlanNodeSource, 'page' | 'layout' | 'html-template'>;
+};
+
+/**
+ * Builds a declared ownership plan from the component dependency graph.
+ *
+ * The plan reflects the declared component dependency graph for one route after
+ * route-root ownership validation has already run. It records ownership shape,
+ * foreign-edge counts, and any validation errors supplied by an earlier
+ * validation pass.
+ */
+export class OwnershipPlanningService {
+	/**
+	 * Builds the structural ownership plan for one route render.
+	 */
+	buildPlan(input: OwnershipPlanBuildInput): OwnershipPlan {
+		const validationErrors = input.validationErrors ?? [];
+		const rendererNames = new Set<string>([input.currentIntegrationName]);
+		let foreignEdgeCount = 0;
+
+		const roots: OwnershipPlanBuildEntry[] = [
+			{ component: input.HtmlTemplate, source: 'html-template' },
+			...(input.Layout ? [{ component: input.Layout, source: 'layout' as const }] : []),
+			{ component: input.Page, source: 'page' },
+		];
+
+		const children = mapDeclaredOwnershipGraph<OwnershipPlanNode>({
+			roots,
+			currentIntegrationName: input.currentIntegrationName,
+			mapNode: ({ component, source, integrationName, componentId, isForeignToParent }, children) => {
+				const componentMeta = component.config?.__eco;
+
+				rendererNames.add(integrationName);
+
+				if (isForeignToParent) {
+					foreignEdgeCount += 1;
+				}
+
+				return {
+					id: componentId,
+					source,
+					ownership: {
+						integrationName,
+						componentId,
+						componentFile: componentMeta?.file,
+						isPageEntry: source === 'page',
+						isForeignToParent,
+					},
+					children,
+					declaredDependenciesValid: true,
+				};
+			},
+		});
+
+		const root: OwnershipPlanNode = {
+			id: `route:${input.routeFile}`,
+			source: 'route',
+			ownership: {
+				integrationName: input.currentIntegrationName,
+				componentId: `route:${input.routeFile}`,
+				componentFile: input.routeFile,
+				isPageEntry: false,
+				isForeignToParent: false,
+			},
+			children,
+			declaredDependenciesValid: validationErrors.length === 0,
+		};
+
+		return {
+			root,
+			rendererNames: Array.from(rendererNames),
+			foreignEdgeCount,
+			hasValidationErrors: validationErrors.length > 0,
+			validationErrors,
+		};
+	}
+}

package/src/route-renderer/orchestration/ownership-validation.service.ts

@@ -0,0 +1,76 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { OwnershipPlanNodeSource, OwnershipValidationError, EcoComponent } from '../../types/public-types.ts';
+import { mapDeclaredOwnershipGraph } from './declared-ownership-graph.ts';
+
+type OwnershipValidationInput = {
+	currentIntegrationName: string;
+	roots: Array<{
+		component: EcoComponent;
+		source: Extract<OwnershipPlanNodeSource, 'page' | 'layout' | 'html-template'>;
+	}>;
+};
+
+/**
+ * Validates foreign ownership as soon as the route root graph is loaded.
+ *
+ * This check runs before route data and dependency preparation so ownership and
+ * metadata problems are surfaced from the loaded component graph itself rather
+ * than being entangled with ownership-plan construction.
+ */
+export class OwnershipValidationService {
+	private readonly appConfig: EcoPagesAppConfig;
+
+	/**
+	 * Creates the ownership validator for one finalized app config.
+	 */
+	constructor(appConfig: EcoPagesAppConfig) {
+		this.appConfig = appConfig;
+	}
+
+	/**
+	 * Validates foreign ownership edges reachable from the supplied route roots.
+	 */
+	validate(input: OwnershipValidationInput): OwnershipValidationError[] {
+		return mapDeclaredOwnershipGraph<OwnershipValidationError[]>({
+			roots: input.roots,
+			currentIntegrationName: input.currentIntegrationName,
+			mapNode: ({ component, integrationName, componentId, isForeignToParent }, children) => {
+				const componentMeta = component.config?.__eco;
+				const errors = children.flat();
+
+				if (!isForeignToParent) {
+					return errors;
+				}
+
+				if (!componentMeta) {
+					errors.push({
+						code: 'MISSING_COMPONENT_METADATA',
+						message: `[ecopages] Foreign child "${componentId}" must provide stable __eco metadata so ownership diagnostics stay actionable. Declared dependencies must include all possible foreign children.`,
+						componentId,
+						integrationName,
+					});
+				}
+
+				if (!this.isRegisteredIntegration(integrationName, input.currentIntegrationName)) {
+					errors.push({
+						code: 'UNKNOWN_INTEGRATION_OWNER',
+						message: `[ecopages] Foreign child "${componentId}" references unknown integration owner "${integrationName}". Declared dependencies must include all possible foreign children and those integrations must be registered.`,
+						componentId,
+						componentFile: componentMeta?.file,
+						integrationName,
+					});
+				}
+
+				return errors;
+			},
+		}).flat();
+	}
+
+	private isRegisteredIntegration(integrationName: string, currentIntegrationName: string): boolean {
+		if (integrationName === currentIntegrationName) {
+			return true;
+		}
+
+		return this.appConfig.integrations.some((integration) => integration.name === integrationName);
+	}
+}

package/src/route-renderer/orchestration/processed-asset-dedupe.ts

@@ -0,0 +1,29 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+
+export function buildProcessedAssetDedupeKey(asset: ProcessedAsset): string {
+	return [
+		asset.kind,
+		asset.position ?? '',
+		asset.srcUrl ?? '',
+		asset.filepath ?? '',
+		asset.content ?? '',
+		asset.inline ? 'inline' : 'external',
+		asset.excludeFromHtml ? 'excluded' : 'included',
+		asset.packageRole ?? '',
+		JSON.stringify(asset.attributes ?? {}),
+	].join('|');
+}
+
+export function dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[] {
+	const unique = new Map<string, ProcessedAsset>();
+
+	for (const asset of assets) {
+		const key = buildProcessedAssetDedupeKey(asset);
+
+		if (!unique.has(key)) {
+			unique.set(key, asset);
+		}
+	}
+
+	return [...unique.values()];
+}

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

@@ -0,0 +1,435 @@
+import { describe, expect, it, vi } from 'vitest';
+import { eco } from '../../eco/eco.ts';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+import type {
+	BaseIntegrationContext,
+	ForeignSubtreeRenderPayload,
+	ComponentRenderInput,
+	EcoComponent,
+} from '../../types/public-types.ts';
+import {
+	QueuedForeignSubtreeResolutionService,
+	type QueuedForeignSubtreeResolutionContext,
+} from './queued-foreign-subtree-resolution.service.ts';
+
+function createComponent(name: string, integration = name): EcoComponent<Record<string, unknown>, string> {
+	return eco.component<Record<string, unknown>, string>({
+		integration,
+		render: () => `<div data-component="${name}"></div>`,
+	});
+}
+
+function createAsset(content: string): ProcessedAsset {
+	return {
+		kind: 'script',
+		inline: true,
+		content,
+		position: 'body',
+	};
+}
+
+function dedupeAssets(assets: ProcessedAsset[]): ProcessedAsset[] {
+	const seen = new Set<string>();
+	const deduped: ProcessedAsset[] = [];
+
+	for (const asset of assets) {
+		const key = JSON.stringify(asset);
+		if (seen.has(key)) {
+			continue;
+		}
+
+		seen.add(key);
+		deduped.push(asset);
+	}
+
+	return deduped;
+}
+
+function applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string {
+	const serializedAttributes = Object.entries(attributes)
+		.map(([name, value]) => ` ${name}="${value}"`)
+		.join('');
+
+	return html.replace(/^<([a-zA-Z][a-zA-Z0-9:-]*)/, `<$1${serializedAttributes}`);
+}
+
+describe('QueuedForeignSubtreeResolutionService', () => {
+	it('creates scoped queue tokens and stores runtime state on the render input', () => {
+		const service = new QueuedForeignSubtreeResolutionService();
+		const shell = createComponent('shell', 'shell');
+		const deferredWidget = createComponent('deferred-widget', 'deferred');
+		const renderInput: ComponentRenderInput = {
+			component: shell,
+			props: {},
+			integrationContext: {
+				componentInstanceId: 'host',
+			},
+		};
+		const rendererCache = new Map<string, unknown>();
+		const originalProps = { label: 'deferred' };
+
+		const runtime = service.createRuntime({
+			renderInput,
+			rendererCache,
+			runtimeContextKey: '__testQueuedForeignSubtreeRuntime',
+			tokenPrefix: '__TEST_QUEUE__',
+			shouldQueueForeignChild: () => true,
+		});
+
+		const interception = runtime.interceptForeignChildSync?.({
+			currentIntegration: 'shell',
+			targetIntegration: 'deferred',
+			component: deferredWidget,
+			props: originalProps,
+		});
+		originalProps.label = 'mutated-after-queue';
+
+		expect(interception).toEqual({
+			kind: 'resolved',
+			value: '__TEST_QUEUE__host__1__',
+		});
+
+		const runtimeContext = service.getRuntimeContext<QueuedForeignSubtreeResolutionContext>(
+			renderInput,
+			'__testQueuedForeignSubtreeRuntime',
+		);
+
+		expect(runtimeContext).toEqual({
+			rendererCache,
+			componentInstanceScope: 'host',
+			nextForeignSubtreeId: 1,
+			queuedResolutions: [
+				{
+					token: '__TEST_QUEUE__host__1__',
+					component: deferredWidget,
+					props: { label: 'deferred' },
+					componentInstanceId: 'host_n_1',
+				},
+			],
+		});
+		expect(renderInput.integrationContext).toEqual(
+			expect.objectContaining({
+				rendererCache,
+			}),
+		);
+	});
+
+	it('preserves existing shared integration context fields when queue runtime state is attached', () => {
+		const service = new QueuedForeignSubtreeResolutionService();
+		const shell = createComponent('shell', 'shell');
+		const renderInput: ComponentRenderInput = {
+			component: shell,
+			props: {},
+			integrationContext: {
+				componentInstanceId: 'host',
+				customKey: 'preserved',
+			} as BaseIntegrationContext & { customKey: string },
+		};
+		const rendererCache = new Map<string, unknown>();
+
+		service.createRuntime({
+			renderInput,
+			rendererCache,
+			runtimeContextKey: '__testQueuedForeignSubtreeRuntime',
+			tokenPrefix: '__TEST_QUEUE__',
+			shouldQueueForeignChild: () => true,
+		});
+
+		expect(renderInput.integrationContext).toEqual(
+			expect.objectContaining({
+				componentInstanceId: 'host',
+				customKey: 'preserved',
+				rendererCache,
+			}),
+		);
+	});
+
+	it('resolves nested queued foreign subtrees, applies root attributes, and dedupes bubbled assets', async () => {
+		const service = new QueuedForeignSubtreeResolutionService();
+		const shell = createComponent('shell', 'shell');
+		const parentForeignSubtree = createComponent('parent-foreign-subtree', 'deferred');
+		const childForeignSubtree = createComponent('child-foreign-subtree', 'deferred');
+		const renderInput: ComponentRenderInput = {
+			component: shell,
+			props: {},
+			integrationContext: {
+				componentInstanceId: 'host',
+			},
+		};
+		const rendererCache = new Map<string, unknown>();
+
+		const runtime = service.createRuntime({
+			renderInput,
+			rendererCache,
+			runtimeContextKey: '__testQueuedForeignSubtreeRuntime',
+			tokenPrefix: '__TEST_QUEUE__',
+			shouldQueueForeignChild: () => true,
+		});
+
+		const parentToken = runtime.interceptForeignChildSync?.({
+			currentIntegration: 'shell',
+			targetIntegration: 'deferred',
+			component: parentForeignSubtree,
+			props: { label: 'parent' },
+		});
+
+		const childToken = runtime.interceptForeignChildSync?.({
+			currentIntegration: 'shell',
+			targetIntegration: 'deferred',
+			component: childForeignSubtree,
+			props: { label: 'child' },
+		});
+
+		const runtimeContext = service.getRuntimeContext<QueuedForeignSubtreeResolutionContext>(
+			renderInput,
+			'__testQueuedForeignSubtreeRuntime',
+		);
+		if (!runtimeContext || parentToken?.kind !== 'resolved' || childToken?.kind !== 'resolved') {
+			throw new Error('Failed to initialize queued foreign-subtree test runtime.');
+		}
+
+		runtimeContext.queuedResolutions[0].props.children = `<slot>${childToken.value}</slot>`;
+
+		const resolveForeignSubtree = vi.fn(
+			async (input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload> => {
+				if (input.component === childForeignSubtree) {
+					return {
+						html: `<span>${String(input.props.label ?? '')}</span>`,
+						attachmentPolicy: { kind: 'first-element' },
+						rootTag: 'span',
+						integrationName: 'deferred',
+						rootAttributes: {
+							'data-owner': 'child',
+							'data-instance': String(
+								(input.integrationContext as { componentInstanceId?: string } | undefined)
+									?.componentInstanceId ?? 'missing',
+							),
+						},
+						assets: [createAsset('shared-asset'), createAsset('child-asset')],
+					};
+				}
+
+				return {
+					html: `<section>${input.children ?? ''}</section>`,
+					attachmentPolicy: { kind: 'first-element' },
+					rootTag: 'section',
+					integrationName: 'deferred',
+					rootAttributes: {
+						'data-owner': 'parent',
+					},
+					assets: [createAsset('shared-asset'), createAsset('parent-asset')],
+				};
+			},
+		);
+
+		const result = await service.resolveQueuedHtml({
+			html: `<article>${parentToken.value}</article>`,
+			runtimeContext,
+			queueLabel: 'Test',
+			renderQueuedChildren: async (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => {
+				if (children === undefined) {
+					return { assets: [], html: undefined };
+				}
+
+				let html = typeof children === 'string' ? children : String(children ?? '');
+
+				for (const token of queuedResolutionsByToken.keys()) {
+					if (!html.includes(token)) {
+						continue;
+					}
+
+					html = html.split(token).join(await resolveToken(token));
+				}
+
+				return {
+					assets: [createAsset('shared-asset'), createAsset('children-asset')],
+					html,
+				};
+			},
+			resolveForeignSubtree,
+			applyAttributesToFirstElement,
+			dedupeProcessedAssets: dedupeAssets,
+		});
+
+		expect(result.html).toBe(
+			'<article><section data-owner="parent"><slot><span data-owner="child" data-instance="host_n_2">child</span></slot></section></article>',
+		);
+		expect(result.assets).toEqual([
+			createAsset('shared-asset'),
+			createAsset('child-asset'),
+			createAsset('children-asset'),
+			createAsset('parent-asset'),
+		]);
+		expect(resolveForeignSubtree).toHaveBeenCalledTimes(2);
+	});
+
+	it('throws when queued foreign subtrees form a cycle', async () => {
+		const service = new QueuedForeignSubtreeResolutionService();
+		const foreignSubtreeA = createComponent('foreign-subtree-a', 'deferred');
+		const foreignSubtreeB = createComponent('foreign-subtree-b', 'deferred');
+		const runtimeContext: QueuedForeignSubtreeResolutionContext = {
+			rendererCache: new Map<string, unknown>(),
+			componentInstanceScope: 'host',
+			nextForeignSubtreeId: 2,
+			queuedResolutions: [
+				{
+					token: '__TEST_QUEUE__host__1__',
+					component: foreignSubtreeA,
+					props: { children: '__TEST_QUEUE__host__2__' },
+					componentInstanceId: 'host_n_1',
+				},
+				{
+					token: '__TEST_QUEUE__host__2__',
+					component: foreignSubtreeB,
+					props: { children: '__TEST_QUEUE__host__1__' },
+					componentInstanceId: 'host_n_2',
+				},
+			],
+		};
+
+		await expect(
+			service.resolveQueuedHtml({
+				html: `<article>__TEST_QUEUE__host__1__</article>`,
+				runtimeContext,
+				queueLabel: 'Test',
+				renderQueuedChildren: async (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => {
+					if (children === undefined) {
+						return { assets: [], html: undefined };
+					}
+
+					let html = typeof children === 'string' ? children : String(children ?? '');
+
+					for (const token of queuedResolutionsByToken.keys()) {
+						if (!html.includes(token)) {
+							continue;
+						}
+
+						html = html.split(token).join(await resolveToken(token));
+					}
+
+					return { assets: [], html };
+				},
+				resolveForeignSubtree: async (input) => ({
+					html: `<section>${input.children ?? ''}</section>`,
+					assets: [],
+					attachmentPolicy: { kind: 'first-element' },
+					rootTag: 'section',
+					integrationName: 'deferred',
+				}),
+				applyAttributesToFirstElement,
+				dedupeProcessedAssets: dedupeAssets,
+			}),
+		).rejects.toThrow('contains a cycle or unresolved dependency links');
+	});
+
+	it('passes structured queued children through to the owning renderer', async () => {
+		const service = new QueuedForeignSubtreeResolutionService();
+		const foreignSubtree = createComponent('foreign-subtree', 'deferred');
+		const structuredChildren = { kind: 'structured-child' };
+		const runtimeContext: QueuedForeignSubtreeResolutionContext = {
+			rendererCache: new Map<string, unknown>(),
+			componentInstanceScope: 'host',
+			nextForeignSubtreeId: 1,
+			queuedResolutions: [
+				{
+					token: '__TEST_QUEUE__host__1__',
+					component: foreignSubtree,
+					props: { children: structuredChildren },
+					componentInstanceId: 'host_n_1',
+				},
+			],
+		};
+
+		const resolveForeignSubtree = vi.fn(
+			async (input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload> => ({
+				html: `<section>${JSON.stringify(input.children)}</section>`,
+				assets: [],
+				attachmentPolicy: { kind: 'first-element' },
+				rootTag: 'section',
+				integrationName: 'deferred',
+			}),
+		);
+
+		const result = await service.resolveQueuedHtml({
+			html: '<article>__TEST_QUEUE__host__1__</article>',
+			runtimeContext,
+			queueLabel: 'Test',
+			renderQueuedChildren: async (children) => ({
+				assets: [],
+				children,
+			}),
+			resolveForeignSubtree,
+			applyAttributesToFirstElement,
+			dedupeProcessedAssets: dedupeAssets,
+		});
+
+		expect(result.html).toBe('<article><section>{"kind":"structured-child"}</section></article>');
+		expect(resolveForeignSubtree).toHaveBeenCalledWith(
+			expect.objectContaining({
+				children: structuredChildren,
+			}),
+			expect.any(Map),
+		);
+	});
+
+	it('resolves queued tokens appended while another token is resolving', async () => {
+		const service = new QueuedForeignSubtreeResolutionService();
+		const parentForeignSubtree = createComponent('parent-foreign-subtree', 'deferred');
+		const childForeignSubtree = createComponent('child-foreign-subtree', 'deferred');
+		const runtimeContext: QueuedForeignSubtreeResolutionContext = {
+			rendererCache: new Map<string, unknown>(),
+			componentInstanceScope: 'host',
+			nextForeignSubtreeId: 1,
+			queuedResolutions: [
+				{
+					token: '__TEST_QUEUE__host__1__',
+					component: parentForeignSubtree,
+					props: {},
+					componentInstanceId: 'host_n_1',
+				},
+			],
+		};
+
+		const resolveForeignSubtree = vi.fn(
+			async (input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload> => {
+				if (input.component === parentForeignSubtree) {
+					runtimeContext.queuedResolutions.push({
+						token: '__TEST_QUEUE__host__2__',
+						component: childForeignSubtree,
+						props: {},
+						componentInstanceId: 'host_n_2',
+					});
+
+					return {
+						html: '<section>__TEST_QUEUE__host__2__</section>',
+						assets: [],
+						attachmentPolicy: { kind: 'first-element' },
+						rootTag: 'section',
+						integrationName: 'deferred',
+					};
+				}
+
+				return {
+					html: '<strong>child</strong>',
+					assets: [],
+					attachmentPolicy: { kind: 'first-element' },
+					rootTag: 'strong',
+					integrationName: 'deferred',
+				};
+			},
+		);
+
+		const result = await service.resolveQueuedHtml({
+			html: '<article>__TEST_QUEUE__host__1__</article>',
+			runtimeContext,
+			queueLabel: 'Test',
+			renderQueuedChildren: async () => ({ assets: [], html: undefined }),
+			resolveForeignSubtree,
+			applyAttributesToFirstElement,
+			dedupeProcessedAssets: dedupeAssets,
+		});
+
+		expect(result.html).toBe('<article><section><strong>child</strong></section></article>');
+		expect(resolveForeignSubtree).toHaveBeenCalledTimes(2);
+	});
+});