@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

package/src/plugins/eco-component-meta-plugin.test.ts

@@ -0,0 +1,380 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createEcoComponentMetaPlugin } from './eco-component-meta-plugin';
+import type { EcoPagesAppConfig } from '../internal-types';
+import { fileSystem } from '@ecopages/file-system';
+
+/**
+ * Creates a regex pattern to match __eco injection with any id hash.
+ * The id is a base36 hash that varies, so we match it with a pattern.
+ */
+function ecoMetaPattern(file: string, integration: string): RegExp {
+	const escapedFile = file.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+	return new RegExp(`__eco: \\{ id: "[a-z0-9]+", file: "${escapedFile}", integration: "${integration}" \\}`);
+}
+
+describe('eco-component-meta-plugin', () => {
+	const Config = {
+		integrations: [
+			{
+				name: 'kitajs',
+				extensions: ['.kita.tsx'],
+			},
+			{
+				name: 'react',
+				extensions: ['.tsx'],
+			},
+			{
+				name: 'ghtml',
+				extensions: ['.ts', '.ghtml.ts'],
+			},
+		],
+	} as EcoPagesAppConfig;
+
+	const plugin = createEcoComponentMetaPlugin({ config: Config });
+
+	async function runPluginOnContent(content: string, filePath: string) {
+		let regexFilter: RegExp | undefined;
+		let onLoadCallback: any;
+
+		const buildMock = {
+			onLoad: (options: { filter: RegExp }, callback: any) => {
+				regexFilter = options.filter;
+				onLoadCallback = callback;
+			},
+		};
+
+		plugin.setup(buildMock as any);
+
+		if (!onLoadCallback || !regexFilter) {
+			throw new Error('Plugin did not register onLoad handler');
+		}
+
+		if (!regexFilter.test(filePath)) {
+			throw new Error(`File path ${filePath} does not match plugin filter ${regexFilter}`);
+		}
+
+		const fileSpy = vi.spyOn(fileSystem, 'readFileSync').mockImplementation(() => content);
+
+		try {
+			return await onLoadCallback({ path: filePath });
+		} finally {
+			fileSpy.mockRestore();
+		}
+	}
+
+	it('should inject __eco into X.config assignment in TSX files', async () => {
+		const content = `
+            MyComponent.config = {
+                dependencies: {}
+            };
+        `;
+
+		const result = await runPluginOnContent(content, '/path/to/component.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/component.tsx', 'react'));
+	});
+
+	it('should NOT inject __eco into config patterns in non-EcoComponent files', async () => {
+		const content = `
+            export const config = {
+                apiUrl: 'https://api.example.com',
+                theme: 'dark'
+            };
+        `;
+
+		const result = await runPluginOnContent(content, '/path/to/settings.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).not.toContain('__eco:');
+	});
+
+	it('should inject __eco into EcoComponent-typed object with config property', async () => {
+		const content = `
+            import type { EcoComponent } from '@ecopages/core';
+
+            export const LitCounter: EcoComponent = {
+                config: {
+                    dependencies: {
+                        scripts: ['lit-counter.script.ts'] } } };
+        `;
+
+		const result = await runPluginOnContent(content, '/path/to/lit-counter.ts');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/lit-counter.ts', 'ghtml'));
+	});
+
+	it('should inject __eco into eco.component() call', async () => {
+		const content = `
+            import { eco } from '@ecopages/core';
+            export const Counter = eco.component${'<CounterProps>'}({
+                dependencies: {
+                    scripts: ['./counter.ts'] },
+                render: () => '${'<div>'}Counter${'</div>'}' });
+        `;
+
+		const result = await runPluginOnContent(content, '/path/to/counter.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/counter.tsx', 'react'));
+		expect(result.contents).toContain('eco.component' + '<CounterProps>({');
+	});
+
+	it('should inject __eco into eco.page call', async () => {
+		const content = `
+            import { eco } from '@ecopages/core';
+            export default eco.page({
+                dependencies: {
+                    components: [] },
+                render: () => '${'<main>'}Page${'</main>'}' });
+        `;
+
+		const result = await runPluginOnContent(content, '/path/to/pages/index.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/pages/index.tsx', 'react'));
+	});
+
+	it('should inject __eco into eco.layout call', async () => {
+		const content = `
+            import { eco } from '@ecopages/core';
+            export const MainLayout = eco.layout({
+                render: ({ children }) => '${'<main>'}' + children + '${'</main>'}' });
+        `;
+
+		const result = await runPluginOnContent(content, '/path/to/layouts/main-layout.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/layouts/main-layout.tsx', 'react'));
+	});
+
+	it('should inject __eco into eco.html call', async () => {
+		const content = `
+            import { eco } from '@ecopages/core';
+            export default eco.html({
+                render: ({ children }) => '${'<html><body>'}' + children + '${'</body></html>'}' });
+        `;
+
+		const result = await runPluginOnContent(content, '/path/to/html.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/html.tsx', 'react'));
+	});
+
+	it('should inject __eco into eco.component() with lazy dependencies', async () => {
+		const content = `
+            export const LazyCounter = eco.component({
+                dependencies: {
+					scripts: [{ src: './counter.ts', lazy: { 'on:interaction': 'click' } }] },
+                render: () => '${'<div>'}Lazy${'</div>'}' });
+        `;
+
+		const result = await runPluginOnContent(content, '/path/to/lazy-counter.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/lazy-counter.tsx', 'react'));
+	});
+
+	it('should detect kitajs integration from .kita.tsx extension', async () => {
+		const content = `import { eco } from '@ecopages/core';
+import type { PageHeadProps } from '@ecopages/core';
+
+export const Head = eco.component<PageHeadProps<string>>({
+	dependencies: {
+		stylesheets: ['../styles/global.css'] },
+	render: ({ metadata, children }) => (
+		<head>
+			<meta charset="UTF-8" />
+			{children}
+		</head>
+	) });`;
+
+		const result = await runPluginOnContent(content, '/path/to/includes/head.kita.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/includes/head.kita.tsx', 'kitajs'));
+	});
+
+	it('should handle eco.page with complex generic types', async () => {
+		const content = `
+import { eco } from '@ecopages/core';
+
+export default eco.page<{ title: string; callback: (arg: string) => void }>({
+	staticProps: async () => ({ props: { title: 'Hello', callback: () => {} } }),
+	render: (props) => '<div>' + props.title + '</div>' });
+`;
+
+		const result = await runPluginOnContent(content, '/path/to/pages/complex.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/pages/complex.tsx', 'react'));
+	});
+
+	it('should handle multiple eco.component calls in same file', async () => {
+		const content = `
+import { eco } from '@ecopages/core';
+
+export const Button = eco.component({
+	render: () => '<button>Click</button>' });
+
+export const Input = eco.component({
+	render: () => '<input type="text" />' });
+`;
+
+		const result = await runPluginOnContent(content, '/path/to/components.tsx');
+
+		expect(result).toBeDefined();
+		const matches = result.contents.match(
+			/__eco: \{ id: "[a-z0-9]+", file: "\/path\/to\/components\.tsx", integration: "react" \},/g,
+		);
+		expect(matches).toHaveLength(2);
+	});
+
+	it('should handle eco.component with empty config object', async () => {
+		const content = `
+import { eco } from '@ecopages/core';
+
+export const Simple = eco.component({});
+`;
+
+		const result = await runPluginOnContent(content, '/path/to/simple.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/simple.tsx', 'react'));
+	});
+
+	it('should not inject into non-eco call expressions', async () => {
+		const content = `
+import { other } from 'some-lib';
+
+export const Thing = other.component({
+	render: () => '<div>Thing</div>' });
+`;
+
+		const result = await runPluginOnContent(content, '/path/to/thing.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).not.toContain('__eco:');
+	});
+
+	it('should not inject into non-config variable declarations', async () => {
+		const content = `
+const settings = {
+	theme: 'dark',
+	locale: 'en' };
+`;
+
+		const result = await runPluginOnContent(content, '/path/to/settings.ts');
+
+		expect(result).toBeDefined();
+		expect(result.contents).not.toContain('__eco:');
+	});
+
+	it('should handle file paths with special characters in directory', async () => {
+		const content = `
+import { eco } from '@ecopages/core';
+
+export default eco.page({
+	render: () => '<div>Page</div>' });
+`;
+
+		const result = await runPluginOnContent(content, '/path/to/my-app/pages/index.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/my-app/pages/index.tsx', 'react'));
+	});
+
+	it('should handle eco.component with nested object in dependencies', async () => {
+		const content = `
+import { eco } from '@ecopages/core';
+
+export const LazyComponent = eco.component({
+	dependencies: {
+		stylesheets: ['./style.css'],
+		scripts: [{ src: './script.ts', lazy: { 'on:interaction': 'click' } }],
+		components: [] },
+	render: () => '<div>Lazy</div>' });
+`;
+
+		const result = await runPluginOnContent(content, '/path/to/lazy.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/lazy.tsx', 'react'));
+	});
+
+	it('should preserve original code structure after injection', async () => {
+		const content = `import { eco } from '@ecopages/core';
+
+export const Counter = eco.component({
+	dependencies: {
+		scripts: ['./counter.ts'] },
+	render: () => '<button>0</button>' });`;
+
+		const result = await runPluginOnContent(content, '/path/to/counter.tsx');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toContain("import { eco } from '@ecopages/core';");
+		expect(result.contents).toContain("scripts: ['./counter.ts']");
+		expect(result.contents).toContain("render: () => '<button>0</button>'");
+	});
+
+	it('should handle query string in file path for cache busting', async () => {
+		const content = `
+import { eco } from '@ecopages/core';
+
+export default eco.page({
+	render: () => '<div>Page</div>' });
+`;
+
+		const result = await runPluginOnContent(content, '/path/to/pages/index.tsx?update=123456');
+
+		expect(result).toBeDefined();
+		expect(result.contents).toMatch(ecoMetaPattern('/path/to/pages/index.tsx', 'react'));
+	});
+
+	describe('Regression: eco-blog views failure', () => {
+		it('should inject __eco into a kitajs page with complex props and no manual __eco', async () => {
+			const content = `import { eco } from '@ecopages/core';
+import { MainLayout } from '@/layouts/main-layout.kita';
+import type { Post } from '@/lib/db';
+
+export interface BlogListProps {
+	posts: Post[];
+}
+
+export const BlogList = eco.page<BlogListProps>({
+	layout: MainLayout,
+	metadata: () => ({
+		title: 'EcoBlog | Home',
+		description: 'A blog about sustainability and technology' }),
+	render: ({ posts }) => {
+		return (
+			<div class="max-w-3xl mx-auto space-y-12">
+                {/* content */}
+			</div>
+		);
+	} });`;
+
+			const result = await runPluginOnContent(
+				content,
+				'/path/to/playground/eco-blog/src/views/blog-list.kita.tsx',
+			);
+
+			expect(result).toBeDefined();
+			expect(result.contents).toMatch(
+				ecoMetaPattern('/path/to/playground/eco-blog/src/views/blog-list.kita.tsx', 'kitajs'),
+			);
+		});
+
+		it('should inject __eco even if the eco call is not at the top level', async () => {
+			const content = `
+                import { eco } from '@ecopages/core';
+                const createPage = () => eco.page({ render: () => 'hi' });
+                export default createPage();
+            `;
+			const result = await runPluginOnContent(content, '/path/to/nested.tsx');
+			expect(result.contents).toMatch(ecoMetaPattern('/path/to/nested.tsx', 'react'));
+		});
+	});
+});

package/src/plugins/eco-component-meta-plugin.ts

@@ -163,6 +163,8 @@ export interface EcoComponentDirPluginOptions {
  * Supported patterns:
  * - `eco.page({ ... })` - Page component declarations
  * - `eco.component({ ... })` - Reusable component declarations
+ * - `eco.html({ ... })` - HTML shell declarations
+ * - `eco.layout({ ... })` - Layout declarations
  * - `Component.config = { ... }` - Config assignment pattern
  * - `config: { ... }` - Config property in object literals
  * - `export const config = { ... }` - Exported config declarations
@@ -260,6 +262,8 @@ interface Insertion {
  * |---------|---------------|---------|------------|
  * | `eco.page({...})` | CallExpression | `export default eco.page({ render: () => 'hi' })` | All |
  * | `eco.component({...})` | CallExpression | `export const Btn = eco.component({ render: () => '<button/>' })` | All |
+ * | `eco.html({...})` | CallExpression | `export default eco.html({ render: () => '<html />' })` | All |
+ * | `eco.layout({...})` | CallExpression | `export const MainLayout = eco.layout({ render: () => '<main />' })` | All |
  * | `X.config = {...}` | AssignmentExpression | `MyComponent.config = { dependencies: [] }` | All |
  * | `config: {...}` | ObjectProperty | `const X: EcoComponent = { config: {...} }` | EcoComponent-typed only |
  *
@@ -289,7 +293,7 @@ function findInjectionPoints(
 	const n = node as Record<string, unknown>;
 
 	/**
-	 * Pattern 1: eco.page({...}) or eco.component({...})
+	 * Pattern 1: eco.page({...}), eco.component({...}), eco.html({...}), or eco.layout({...})
 	 * AST structure: CallExpression with MemberExpression callee where object is "eco"
 	 */
 	if (n.type === 'CallExpression') {
@@ -303,11 +307,14 @@ function findInjectionPoints(
 			const obj = callee.object as Record<string, unknown> | undefined;
 			const prop = callee.property as Record<string, unknown> | undefined;
 
-			/** Check: is this `eco.page(...)` or `eco.component(...)`? */
+			/** Check: is this `eco.page(...)`, `eco.component(...)`, `eco.html(...)`, or `eco.layout(...)`? */
 			if (
 				obj?.type === 'Identifier' &&
 				obj?.name === 'eco' &&
-				(prop?.name === 'page' || prop?.name === 'component')
+				(prop?.name === 'page' ||
+					prop?.name === 'component' ||
+					prop?.name === 'html' ||
+					prop?.name === 'layout')
 			) {
 				/** Get the first argument - should be an object literal {...} */
 				const args = n.arguments as Array<Record<string, unknown>> | undefined;

package/src/plugins/integration-plugin.test.ts

@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { IntegrationPlugin, type IntegrationPluginConfig } from './integration-plugin';
+import type { IHmrManager } from '../public-types';
+import type { AssetDefinition } from '../services/assets/asset-processing-service';
+
+class TestIntegrationPlugin extends IntegrationPlugin {
+	renderer = vi.fn() as any;
+	override setup(): Promise<void> {
+		return Promise.resolve();
+	}
+
+	override teardown(): Promise<void> {
+		return Promise.resolve();
+	}
+}
+
+describe('IntegrationPlugin', () => {
+	let plugin: TestIntegrationPlugin;
+	const config: IntegrationPluginConfig = {
+		name: 'test-plugin',
+		extensions: ['.test'],
+		integrationDependencies: [],
+	};
+
+	beforeEach(() => {
+		plugin = new TestIntegrationPlugin(config);
+	});
+
+	it('should initialize with correct config values', () => {
+		expect(plugin.name).toBe(config.name);
+		expect(plugin.extensions).toEqual(config.extensions);
+		expect(plugin.runtimeCapability).toBeUndefined();
+		expect(plugin.getResolvedIntegrationDependencies()).toEqual(
+			config.integrationDependencies as AssetDefinition[],
+		);
+	});
+
+	it('should retain runtime capability declarations', () => {
+		const pluginWithRuntimeCapability = new TestIntegrationPlugin({
+			name: 'runtime-capable',
+			extensions: ['.test'],
+			runtimeCapability: {
+				tags: ['bun-only'],
+				minRuntimeVersion: '1.0.0',
+			},
+		});
+
+		expect(pluginWithRuntimeCapability.runtimeCapability).toEqual({
+			tags: ['bun-only'],
+			minRuntimeVersion: '1.0.0',
+		});
+	});
+
+	it('should initialize with empty dependencies if not provided', () => {
+		const pluginWithoutDeps = new TestIntegrationPlugin({
+			name: 'test',
+			extensions: [],
+		});
+		expect(pluginWithoutDeps.getResolvedIntegrationDependencies()).toEqual([]);
+	});
+
+	it('should implement setup and teardown methods', async () => {
+		await expect(plugin.setup()).resolves.toBeUndefined();
+		await expect(plugin.teardown()).resolves.toBeUndefined();
+	});
+
+	it('should not defer component boundaries by default', () => {
+		expect(
+			plugin.shouldDeferComponentBoundary({
+				currentIntegration: 'ghtml',
+				targetIntegration: 'react',
+				component: () => '<div></div>',
+			}),
+		).toBe(false);
+	});
+
+	it('should register runtime specifier maps through the base HMR setup', () => {
+		const registerSpecifierMap = vi.fn();
+		const hmrManager = {
+			registerSpecifierMap,
+			registerStrategy: vi.fn(),
+			registerEntrypoint: vi.fn(),
+			registerScriptEntrypoint: vi.fn(),
+			setPlugins: vi.fn(),
+			setEnabled: vi.fn(),
+			isEnabled: vi.fn(() => true),
+			broadcast: vi.fn(),
+			getOutputUrl: vi.fn(),
+			getWatchedFiles: vi.fn(() => new Map()),
+			getSpecifierMap: vi.fn(() => new Map()),
+			getDistDir: vi.fn(() => ''),
+			getPlugins: vi.fn(() => []),
+			getDefaultContext: vi.fn(),
+			handleFileChange: vi.fn(),
+		} satisfies IHmrManager;
+
+		const pluginWithRuntimeSpecifiers = new (class extends TestIntegrationPlugin {
+			override getRuntimeSpecifierMap(): Record<string, string> {
+				return {
+					'test-runtime': '/assets/vendors/test-runtime.js',
+				};
+			}
+		})(config);
+
+		pluginWithRuntimeSpecifiers.setHmrManager(hmrManager);
+
+		expect(registerSpecifierMap).toHaveBeenCalledWith({
+			'test-runtime': '/assets/vendors/test-runtime.js',
+		});
+	});
+});

package/src/plugins/integration-plugin.ts

@@ -2,9 +2,12 @@ import type { EcoBuildPlugin } from '../build/build-types';
 import type { EcoPagesAppConfig, IHmrManager } from '../internal-types';
 import type { HmrStrategy } from '../hmr/hmr-strategy';
 import type { EcoComponent, EcoPagesElement } from '../public-types';
-import type { IntegrationRenderer } from '../route-renderer/integration-renderer';
-import { AssetProcessingService } from '../services/asset-processing-service/asset-processing.service';
-import type { AssetDefinition, ProcessedAsset } from '../services/asset-processing-service/assets.types';
+import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer';
+import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service';
+import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types';
+import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
+
+export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
 
 export const INTEGRATION_PLUGIN_ERRORS = {
 	NOT_INITIALIZED_WITH_APP_CONFIG: 'Plugin not initialized with app config',
@@ -33,6 +36,11 @@ export interface IntegrationPluginConfig {
 	 * @default 'render'
 	 */
 	staticBuildStep?: 'render' | 'fetch';
+	/**
+	 * Declares runtime-specific requirements that must be satisfied before the
+	 * app can start with this integration enabled.
+	 */
+	runtimeCapability?: RuntimeCapabilityDeclaration;
 }
 
 /**
@@ -59,6 +67,7 @@ export abstract class IntegrationPlugin<C = EcoPagesElement> {
 	readonly extensions: string[];
 	abstract renderer: RendererClass<C>;
 	readonly staticBuildStep: 'render' | 'fetch';
+	readonly runtimeCapability?: RuntimeCapabilityDeclaration;
 
 	protected integrationDependencies: AssetDefinition[];
 	protected resolvedIntegrationDependencies: ProcessedAsset[] = [];
@@ -77,6 +86,7 @@ export abstract class IntegrationPlugin<C = EcoPagesElement> {
 		this.extensions = config.extensions;
 		this.integrationDependencies = config.integrationDependencies || [];
 		this.staticBuildStep = config.staticBuildStep || 'render';
+		this.runtimeCapability = config.runtimeCapability;
 	}
 
 	setConfig(appConfig: EcoPagesAppConfig): void {
@@ -104,8 +114,26 @@ export abstract class IntegrationPlugin<C = EcoPagesElement> {
 	 */
 	getHmrStrategy?(): HmrStrategy | undefined;
 
+	/**
+	 * Returns bare-specifier mappings that should be registered in the active
+	 * runtime specifier registry.
+	 *
+	 * @remarks
+	 * Override this when the integration owns browser runtime bundles that must
+	 * be addressable from client-side imports through stable bare specifiers.
+	 *
+	 * Today these mappings are consumed by the development runtime and browser
+	 * bundle aliasing path. They are intentionally generic enough to grow into a
+	 * broader import-map-style facility later without moving framework-specific
+	 * map contents into core.
+	 */
+	getRuntimeSpecifierMap(): Record<string, string> {
+		return {};
+	}
+
 	setHmrManager(hmrManager: IHmrManager) {
 		this.hmrManager = hmrManager;
+		hmrManager.registerSpecifierMap(this.getRuntimeSpecifierMap());
 
 		const strategy = this.getHmrStrategy?.();
 		if (strategy) {
@@ -169,6 +197,20 @@ export abstract class IntegrationPlugin<C = EcoPagesElement> {
 		return false;
 	}
 
+	/**
+	 * Prepares build-facing contributions before the app build manifest is sealed.
+	 *
+	 * @remarks
+	 * Override this when an integration needs to materialize runtime/build plugin
+	 * declarations ahead of runtime startup. Keep runtime-only side effects out of
+	 * this hook; they belong in `setup()`.
+	 */
+	async prepareBuildContributions(): Promise<void> {}
+
+	/**
+	 * Performs runtime-only integration setup after config build has already
+	 * sealed manifest contributions.
+	 */
 	async setup(): Promise<void> {
 		if (this.integrationDependencies.length === 0) return;
 		if (!this.assetProcessingService) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_ASSET_SERVICE);