@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.24

package/src/route-renderer/orchestration/page-packaging.service.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+import { PagePackagingService } from './page-packaging.service.ts';
+
+describe('PagePackagingService', () => {
+	it('classifies page assets, inline assets, separate assets, and dynamic chunks', () => {
+		const service = new PagePackagingService();
+		const pageScript = {
+			kind: 'script',
+			srcUrl: '/assets/page.js',
+			position: 'head',
+		} as ProcessedAsset;
+		const pageStylesheet = {
+			kind: 'stylesheet',
+			srcUrl: '/assets/page.css',
+			position: 'head',
+		} as ProcessedAsset;
+		const runtimeScript = {
+			kind: 'script',
+			srcUrl: '/assets/vendors/react.js',
+			position: 'head',
+			excludeFromHtml: true,
+			packageRole: 'runtime',
+		} as ProcessedAsset;
+		const inlineScript = {
+			kind: 'script',
+			content: 'console.log("inline")',
+			inline: true,
+			position: 'head',
+		} as ProcessedAsset;
+		const dynamicChunk = {
+			kind: 'script',
+			srcUrl: '/assets/chunks/page-chunk.js',
+			position: 'head',
+			packageRole: 'dynamic-chunk',
+		} as ProcessedAsset;
+
+		const result = service.createPagePackage([
+			pageStylesheet,
+			pageScript,
+			runtimeScript,
+			inlineScript,
+			dynamicChunk,
+		]);
+
+		expect(result.pageScript).toBe(pageScript);
+		expect(result.pageStylesheet).toBe(pageStylesheet);
+		expect(result.htmlAssets).toEqual([pageStylesheet, pageScript, inlineScript, dynamicChunk]);
+		expect(result.inlineAssets).toEqual([inlineScript]);
+		expect(result.separateAssets).toEqual([runtimeScript]);
+		expect(result.dynamicChunks).toEqual([dynamicChunk]);
+	});
+
+	it('prefers explicit page roles over visibility heuristics', () => {
+		const service = new PagePackagingService();
+		const hiddenPageScript = {
+			kind: 'script',
+			srcUrl: '/assets/pages/index.js',
+			position: 'head',
+			excludeFromHtml: true,
+			packageRole: 'page-script',
+		} as ProcessedAsset;
+		const hydrationBootstrap = {
+			kind: 'script',
+			srcUrl: '/assets/pages/index-hydration.js',
+			position: 'head',
+			packageRole: 'keep-separate',
+		} as ProcessedAsset;
+
+		const result = service.createPagePackage([hiddenPageScript, hydrationBootstrap]);
+
+		expect(result.pageScript).toBe(hiddenPageScript);
+		expect(result.htmlAssets).toEqual([hydrationBootstrap]);
+		expect(result.separateAssets).toEqual([hydrationBootstrap]);
+	});
+});

package/src/route-renderer/orchestration/page-packaging.service.ts

@@ -0,0 +1,85 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+import type { PagePackageResult } from '../../types/public-types.ts';
+
+/**
+ * Creates the structured page package consumed by final HTML injection.
+ *
+ * This first pass is intentionally behavior-preserving. It establishes the
+ * packaging seam while forwarding the current flat processed asset list.
+ */
+export class PagePackagingService {
+	/**
+	 * Partitions processed assets into the page-level groups used during final
+	 * HTML injection and post-processing.
+	 */
+	createPagePackage(assets: ProcessedAsset[]): PagePackageResult {
+		const inlineAssets: ProcessedAsset[] = [];
+		const separateAssets: ProcessedAsset[] = [];
+		const dynamicChunks: ProcessedAsset[] = [];
+		let pageScript: ProcessedAsset | undefined;
+		let pageStylesheet: ProcessedAsset | undefined;
+
+		for (const asset of assets) {
+			if (asset.inline) {
+				inlineAssets.push(asset);
+				continue;
+			}
+
+			if (asset.packageRole === 'dynamic-chunk') {
+				dynamicChunks.push(asset);
+				continue;
+			}
+
+			if (!pageScript && asset.packageRole === 'page-script') {
+				pageScript = asset;
+				continue;
+			}
+
+			if (!pageStylesheet && asset.packageRole === 'page-style') {
+				pageStylesheet = asset;
+				continue;
+			}
+
+			if (asset.packageRole === 'keep-separate' || asset.packageRole === 'runtime') {
+				separateAssets.push(asset);
+				continue;
+			}
+
+			if (!pageScript && asset.kind === 'script' && !asset.excludeFromHtml) {
+				pageScript = asset;
+				continue;
+			}
+
+			if (!pageStylesheet && asset.kind === 'stylesheet') {
+				pageStylesheet = asset;
+				continue;
+			}
+
+			separateAssets.push(asset);
+		}
+
+		const htmlAssets = assets.filter((asset) => this.shouldIncludeInHtml(asset));
+
+		return {
+			assets,
+			htmlAssets,
+			pageScript,
+			pageStylesheet,
+			inlineAssets,
+			separateAssets,
+			dynamicChunks,
+		};
+	}
+
+	private shouldIncludeInHtml(asset: ProcessedAsset): boolean {
+		if (asset.excludeFromHtml) {
+			return false;
+		}
+
+		if (asset.packageRole === 'runtime') {
+			return false;
+		}
+
+		return true;
+	}
+}

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

@@ -0,0 +1,25 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+
+export function dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[] {
+	const unique = new Map<string, ProcessedAsset>();
+
+	for (const asset of assets) {
+		const key = [
+			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('|');
+
+		if (!unique.has(key)) {
+			unique.set(key, asset);
+		}
+	}
+
+	return [...unique.values()];
+}

package/src/route-renderer/orchestration/queued-boundary-runtime.service.test.ts

@@ -0,0 +1,319 @@
+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,
+	BoundaryRenderPayload,
+	ComponentRenderInput,
+	EcoComponent,
+} from '../../types/public-types.ts';
+import { QueuedBoundaryRuntimeService, type QueuedBoundaryRuntimeContext } from './queued-boundary-runtime.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('QueuedBoundaryRuntimeService', () => {
+	it('creates scoped queue tokens and stores runtime state on the boundary input', () => {
+		const service = new QueuedBoundaryRuntimeService();
+		const shell = createComponent('shell', 'shell');
+		const deferredWidget = createComponent('deferred-widget', 'deferred');
+		const boundaryInput: ComponentRenderInput = {
+			component: shell,
+			props: {},
+			integrationContext: {
+				componentInstanceId: 'host',
+			},
+		};
+		const rendererCache = new Map<string, unknown>();
+		const originalProps = { label: 'deferred' };
+
+		const runtime = service.createRuntime({
+			boundaryInput,
+			rendererCache,
+			runtimeContextKey: '__testQueuedBoundaryRuntime',
+			tokenPrefix: '__TEST_QUEUE__',
+			shouldQueueBoundary: () => true,
+		});
+
+		const interception = runtime.interceptBoundarySync?.({
+			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<QueuedBoundaryRuntimeContext>(
+			boundaryInput,
+			'__testQueuedBoundaryRuntime',
+		);
+
+		expect(runtimeContext).toEqual({
+			rendererCache,
+			componentInstanceScope: 'host',
+			nextBoundaryId: 1,
+			queuedResolutions: [
+				{
+					token: '__TEST_QUEUE__host__1__',
+					component: deferredWidget,
+					props: { label: 'deferred' },
+					componentInstanceId: 'host_n_1',
+				},
+			],
+		});
+		expect(boundaryInput.integrationContext).toEqual(
+			expect.objectContaining({
+				rendererCache,
+			}),
+		);
+	});
+
+	it('preserves existing shared integration context fields when queue runtime state is attached', () => {
+		const service = new QueuedBoundaryRuntimeService();
+		const shell = createComponent('shell', 'shell');
+		const boundaryInput: ComponentRenderInput = {
+			component: shell,
+			props: {},
+			integrationContext: {
+				componentInstanceId: 'host',
+				customKey: 'preserved',
+			} as BaseIntegrationContext & { customKey: string },
+		};
+		const rendererCache = new Map<string, unknown>();
+
+		service.createRuntime({
+			boundaryInput,
+			rendererCache,
+			runtimeContextKey: '__testQueuedBoundaryRuntime',
+			tokenPrefix: '__TEST_QUEUE__',
+			shouldQueueBoundary: () => true,
+		});
+
+		expect(boundaryInput.integrationContext).toEqual(
+			expect.objectContaining({
+				componentInstanceId: 'host',
+				customKey: 'preserved',
+				rendererCache,
+			}),
+		);
+	});
+
+	it('resolves nested queued boundaries, applies root attributes, and dedupes bubbled assets', async () => {
+		const service = new QueuedBoundaryRuntimeService();
+		const shell = createComponent('shell', 'shell');
+		const parentBoundary = createComponent('parent-boundary', 'deferred');
+		const childBoundary = createComponent('child-boundary', 'deferred');
+		const boundaryInput: ComponentRenderInput = {
+			component: shell,
+			props: {},
+			integrationContext: {
+				componentInstanceId: 'host',
+			},
+		};
+		const rendererCache = new Map<string, unknown>();
+
+		const runtime = service.createRuntime({
+			boundaryInput,
+			rendererCache,
+			runtimeContextKey: '__testQueuedBoundaryRuntime',
+			tokenPrefix: '__TEST_QUEUE__',
+			shouldQueueBoundary: () => true,
+		});
+
+		const parentToken = runtime.interceptBoundarySync?.({
+			currentIntegration: 'shell',
+			targetIntegration: 'deferred',
+			component: parentBoundary,
+			props: { label: 'parent' },
+		});
+
+		const childToken = runtime.interceptBoundarySync?.({
+			currentIntegration: 'shell',
+			targetIntegration: 'deferred',
+			component: childBoundary,
+			props: { label: 'child' },
+		});
+
+		const runtimeContext = service.getRuntimeContext<QueuedBoundaryRuntimeContext>(
+			boundaryInput,
+			'__testQueuedBoundaryRuntime',
+		);
+		if (!runtimeContext || parentToken?.kind !== 'resolved' || childToken?.kind !== 'resolved') {
+			throw new Error('Failed to initialize queued boundary test runtime.');
+		}
+
+		runtimeContext.queuedResolutions[0].props.children = `<slot>${childToken.value}</slot>`;
+
+		const resolveBoundary = vi.fn(async (input: ComponentRenderInput): Promise<BoundaryRenderPayload> => {
+			if (input.component === childBoundary) {
+				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,
+				};
+			},
+			resolveBoundary,
+			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(resolveBoundary).toHaveBeenCalledTimes(2);
+	});
+
+	it('throws when queued boundaries form a cycle', async () => {
+		const service = new QueuedBoundaryRuntimeService();
+		const boundaryA = createComponent('boundary-a', 'deferred');
+		const boundaryB = createComponent('boundary-b', 'deferred');
+		const runtimeContext: QueuedBoundaryRuntimeContext = {
+			rendererCache: new Map<string, unknown>(),
+			componentInstanceScope: 'host',
+			nextBoundaryId: 2,
+			queuedResolutions: [
+				{
+					token: '__TEST_QUEUE__host__1__',
+					component: boundaryA,
+					props: { children: '__TEST_QUEUE__host__2__' },
+					componentInstanceId: 'host_n_1',
+				},
+				{
+					token: '__TEST_QUEUE__host__2__',
+					component: boundaryB,
+					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 };
+				},
+				resolveBoundary: 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');
+	});
+});