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

package/src/hmr/client/hmr-runtime.ts

@@ -0,0 +1,160 @@
+/**
+ * Ecopages HMR Runtime
+ * Injected into the browser to handle Hot Module Replacement updates.
+ */
+
+import { getEcoNavigationRuntime } from '../../router/client/navigation-coordinator.ts';
+
+interface HMRPayload {
+	type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
+	path?: string;
+	message?: string;
+	timestamp?: number;
+}
+
+(function () {
+	const WS_URL = 'ws://' + location.host + '/_hmr';
+	let socket: WebSocket;
+	let reconnectAttempts = 0;
+
+	function connect() {
+		socket = new WebSocket(WS_URL);
+
+		socket.addEventListener('open', () => {
+			console.log('[ecopages] HMR Connected');
+			reconnectAttempts = 0;
+		});
+
+		socket.addEventListener('message', async (event) => {
+			try {
+				const payload: HMRPayload = JSON.parse(event.data);
+				handleMessage(payload);
+			} catch (e) {
+				console.error('[ecopages] Invalid HMR message:', e);
+			}
+		});
+
+		socket.addEventListener('close', () => {
+			if (reconnectAttempts < 10) {
+				setTimeout(connect, 1000 * 2 ** reconnectAttempts);
+				reconnectAttempts++;
+			}
+		});
+	}
+
+	async function handleMessage(payload: HMRPayload) {
+		const navigationRuntime = getEcoNavigationRuntime(window);
+
+		switch (payload.type) {
+			case 'reload':
+				await waitForNavigationToSettle(navigationRuntime);
+				location.reload();
+				break;
+			case 'layout-update': {
+				await waitForNavigationToSettle(navigationRuntime);
+				if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
+				} else {
+					location.reload();
+				}
+				break;
+			}
+			case 'error':
+				console.error('[ecopages] HMR Error:', payload.message);
+				break;
+			case 'update':
+				if (payload.path) {
+					await applyUpdate(payload.path, payload.timestamp);
+				}
+				break;
+			case 'css-update':
+				if (payload.path) {
+					refreshStylesheet(payload.path);
+				}
+				break;
+		}
+	}
+
+	/**
+	 * Applies a module update by calling registered HMR handlers or re-importing the module.
+	 * @param path - The module path to update
+	 * @param timestamp - Optional timestamp for cache busting
+	 */
+	async function applyUpdate(path: string, timestamp?: number) {
+		try {
+			const url = path + '?t=' + (timestamp || Date.now());
+			const handlers = window.__ECO_PAGES__?.hmrHandlers;
+			const navigationRuntime = getEcoNavigationRuntime(window);
+			await waitForNavigationToSettle(navigationRuntime);
+
+			if (handlers?.[path]) {
+				await handlers[path](url);
+				return;
+			}
+
+			await import(url);
+
+			if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
+			}
+		} catch (e) {
+			console.error('[ecopages] Failed to apply HMR update:', e);
+		}
+	}
+
+	function getActiveHmrModuleUrl(): string | undefined {
+		const pageModule = window.__ECO_PAGES__?.page?.module;
+		if (pageModule && pageModule.includes('/assets/_hmr/')) {
+			return pageModule.split('?')[0];
+		}
+
+		const handlerPaths = Object.keys(window.__ECO_PAGES__?.hmrHandlers ?? {});
+		return handlerPaths.at(-1);
+	}
+
+	async function waitForNavigationToSettle(navigationRuntime: ReturnType<typeof getEcoNavigationRuntime>) {
+		if (!navigationRuntime.hasPendingNavigationTransaction()) {
+			return;
+		}
+
+		await new Promise<void>((resolve) => {
+			const startedAt = performance.now();
+			const timeoutMs = 2000;
+
+			const poll = () => {
+				if (!navigationRuntime.hasPendingNavigationTransaction()) {
+					resolve();
+					return;
+				}
+
+				if (performance.now() - startedAt >= timeoutMs) {
+					resolve();
+					return;
+				}
+
+				requestAnimationFrame(poll);
+			};
+
+			requestAnimationFrame(poll);
+		});
+	}
+
+	/**
+	 * Hot-reload CSS by updating stylesheet link href with cache-busting query param.
+	 * This causes the browser to re-fetch the stylesheet without a full page reload.
+	 */
+	function refreshStylesheet(path: string) {
+		const filename = path.split('/').pop() || '';
+		const links = document.querySelectorAll('link[rel="stylesheet"]');
+
+		links.forEach((link) => {
+			const href = (link as HTMLLinkElement).href;
+			if (href.includes(filename) || href.includes(path.replace(/^.*\/src\//, '/assets/'))) {
+				const url = new URL(href, location.origin);
+				url.searchParams.set('t', Date.now().toString());
+				(link as HTMLLinkElement).href = url.toString();
+				console.log('[ecopages] CSS updated:', filename);
+			}
+		});
+	}
+
+	connect();
+})();

package/src/hmr/hmr-strategy.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import { HmrStrategy, HmrStrategyType, type HmrAction } from './hmr-strategy';
+
+/**
+ * Mock strategy for testing the base class behavior
+ */
+class MockStrategy extends HmrStrategy {
+	readonly type: HmrStrategyType;
+	override readonly priorityOffset: number;
+	private matchPattern: string;
+
+	constructor(options: { type: HmrStrategyType; priorityOffset?: number; matchPattern?: string }) {
+		super();
+		this.type = options.type;
+		this.priorityOffset = options.priorityOffset ?? 0;
+		this.matchPattern = options.matchPattern ?? '.';
+	}
+
+	matches(filePath: string): boolean {
+		return filePath.endsWith(this.matchPattern);
+	}
+
+	async process(filePath: string): Promise<HmrAction> {
+		return {
+			type: 'broadcast',
+			events: [{ type: 'update', path: filePath, timestamp: Date.now() }],
+		};
+	}
+}
+
+describe('HmrStrategyType', () => {
+	it('INTEGRATION has value 100', () => {
+		expect(HmrStrategyType.INTEGRATION).toBe(100);
+	});
+
+	it('ASSET has value 50', () => {
+		expect(HmrStrategyType.ASSET).toBe(50);
+	});
+
+	it('SCRIPT has value 25', () => {
+		expect(HmrStrategyType.SCRIPT).toBe(25);
+	});
+
+	it('FALLBACK has value 0', () => {
+		expect(HmrStrategyType.FALLBACK).toBe(0);
+	});
+
+	it('maintains priority order: INTEGRATION > ASSET > SCRIPT > FALLBACK', () => {
+		expect(HmrStrategyType.INTEGRATION).toBeGreaterThan(HmrStrategyType.ASSET);
+		expect(HmrStrategyType.ASSET).toBeGreaterThan(HmrStrategyType.SCRIPT);
+		expect(HmrStrategyType.SCRIPT).toBeGreaterThan(HmrStrategyType.FALLBACK);
+	});
+});
+
+describe('HmrStrategy', () => {
+	describe('priority', () => {
+		it('returns type value when priorityOffset is 0', () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.INTEGRATION });
+			expect(strategy.priority).toBe(100);
+		});
+
+		it('returns type + priorityOffset', () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.INTEGRATION, priorityOffset: 5 });
+			expect(strategy.priority).toBe(105);
+		});
+
+		it('allows negative priorityOffset', () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.ASSET, priorityOffset: -10 });
+			expect(strategy.priority).toBe(40);
+		});
+	});
+
+	describe('strategy selection by priority', () => {
+		it('higher priority strategies are selected first', () => {
+			const strategies = [
+				new MockStrategy({ type: HmrStrategyType.FALLBACK, matchPattern: '.test' }),
+				new MockStrategy({ type: HmrStrategyType.INTEGRATION, matchPattern: '.test' }),
+				new MockStrategy({ type: HmrStrategyType.SCRIPT, matchPattern: '.test' }),
+				new MockStrategy({ type: HmrStrategyType.ASSET, matchPattern: '.test' }),
+			];
+
+			const sorted = [...strategies].sort((a, b) => b.priority - a.priority);
+
+			expect(sorted[0].type).toBe(HmrStrategyType.INTEGRATION);
+			expect(sorted[1].type).toBe(HmrStrategyType.ASSET);
+			expect(sorted[2].type).toBe(HmrStrategyType.SCRIPT);
+			expect(sorted[3].type).toBe(HmrStrategyType.FALLBACK);
+		});
+
+		it('priorityOffset can override default ordering', () => {
+			const assetWithHighOffset = new MockStrategy({
+				type: HmrStrategyType.ASSET,
+				priorityOffset: 60,
+				matchPattern: '.test',
+			});
+			const integration = new MockStrategy({
+				type: HmrStrategyType.INTEGRATION,
+				matchPattern: '.test',
+			});
+
+			expect(assetWithHighOffset.priority).toBeGreaterThan(integration.priority);
+		});
+	});
+
+	describe('matches', () => {
+		it('should be implemented by subclasses', () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.ASSET, matchPattern: '.css' });
+			expect(strategy.matches('styles.css')).toBe(true);
+			expect(strategy.matches('script.js')).toBe(false);
+		});
+	});
+
+	describe('process', () => {
+		it('should return an HmrAction', async () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.ASSET });
+			const action = await strategy.process('/path/to/file.');
+
+			expect(action.type).toBe('broadcast');
+			expect(action.events).toBeDefined();
+			expect(action.events?.[0].type).toBe('update');
+			expect(action.events?.[0].path).toBe('/path/to/file.');
+		});
+	});
+});

package/src/hmr/hmr-strategy.ts

@@ -0,0 +1,177 @@
+import type { ClientBridgeEvent } from '../types/public-types.ts';
+
+/**
+ * HMR Strategy Pattern
+ *
+ * This module defines the base classes and types for Hot Module Replacement strategies.
+ * Each strategy handles a specific type of file change and determines how to process it.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * class CustomHmrStrategy extends HmrStrategy {
+ *   readonly type = HmrStrategyType.INTEGRATION;
+ *
+ *   matches(filePath: string): boolean {
+ *     return filePath.endsWith('.custom');
+ *   }
+ *
+ *   async process(filePath: string): Promise<HmrAction> {
+ *     return {
+ *       type: 'broadcast',
+ *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }],
+ *     };
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Defines the category of an HMR strategy, which determines its execution priority.
+ * Strategies are evaluated in descending order: INTEGRATION → ASSET → SCRIPT → FALLBACK.
+ *
+ * @remarks
+ * The numeric values represent base priorities. Strategies can fine-tune their priority
+ * using the `priorityOffset` property.
+ */
+export const HmrStrategyType = {
+	/**
+	 * Integration-specific strategies (React, Lit, etc.)
+	 * Highest priority to allow framework-specific HMR handling.
+	 */
+	INTEGRATION: 100,
+
+	/**
+	 * Asset processing strategies (CSS, images, etc.)
+	 * High priority for specialized asset handling.
+	 */
+	ASSET: 50,
+
+	/**
+	 * Generic script bundling strategies (JS/TS)
+	 * Medium priority for standard script processing.
+	 */
+	SCRIPT: 25,
+
+	/**
+	 * Fallback strategy for unhandled file types.
+	 * Lowest priority, triggers full page reload.
+	 */
+	FALLBACK: 0,
+} as const;
+
+export type HmrStrategyType = (typeof HmrStrategyType)[keyof typeof HmrStrategyType];
+
+/**
+ * Represents an action to be taken after processing a file change.
+ */
+export interface HmrAction {
+	/**
+	 * Whether to broadcast an HMR event to connected clients.
+	 */
+	type: 'broadcast' | 'none';
+
+	/**
+	 * The HMR events to broadcast, if type is 'broadcast'.
+	 * Multiple events may be broadcast in one action.
+	 */
+	events?: ClientBridgeEvent[];
+}
+
+/**
+ * Base class for HMR strategies.
+ *
+ * Each strategy handles a specific type of file change and determines how to process it.
+ * Strategies are selected based on their priority (higher values are evaluated first) and
+ * whether they match the changed file path.
+ *
+ * @remarks
+ * Strategies are expected to be stateless and idempotent. The same file change
+ * should produce the same result when processed by the same strategy.
+ *
+ * @example
+ * ```typescript
+ * class MyAssetStrategy extends HmrStrategy {
+ *   readonly type = HmrStrategyType.ASSET;
+ *   readonly priorityOffset = 5;
+ *
+ *   matches(filePath: string): boolean {
+ *     return /\.(png|jpg|svg)$/.test(filePath);
+ *   }
+ *
+ *   async process(filePath: string): Promise<HmrAction> {
+ *     await this.optimizeImage(filePath);
+ *     return {
+ *       type: 'broadcast',
+ *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }]
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export abstract class HmrStrategy {
+	/**
+	 * The category of this strategy, determining its base priority.
+	 */
+	abstract readonly type: HmrStrategyType;
+
+	/**
+	 * Optional offset to fine-tune priority within the same category.
+	 * Useful when multiple strategies share the same type.
+	 *
+	 * @defaultValue 0
+	 */
+	readonly priorityOffset: number = 0;
+
+	/**
+	 * Computed priority for strategy selection.
+	 * Higher values are evaluated first.
+	 *
+	 * @returns The sum of the strategy type and priority offset
+	 */
+	get priority(): number {
+		return this.type + this.priorityOffset;
+	}
+
+	/**
+	 * Determines if this strategy can handle the given file path.
+	 *
+	 * @param filePath - Absolute path to the changed file
+	 * @returns `true` when this strategy should process the file
+	 *
+	 * @example
+	 * ```typescript
+	 * matches(filePath: string): boolean {
+	 *   return filePath.endsWith('.css');
+	 * }
+	 * ```
+	 */
+	abstract matches(filePath: string): boolean;
+
+	/**
+	 * Processes a file change and returns the action to take.
+	 *
+	 * This method may perform side effects such as:
+	 * - Rebuilding files
+	 * - Writing to disk
+	 * - Transforming code
+	 * - Updating caches
+	 *
+	 * @param filePath - Absolute path to the changed file
+	 * @returns Action to take (broadcast event or none)
+	 *
+	 * @example
+	 * ```typescript
+	 * async process(filePath: string): Promise<HmrAction> {
+	 *   const processed = await this.transform(filePath);
+	 *   await Bun.write(outputPath, processed);
+	 *
+	 *   return {
+	 *     type: 'broadcast',
+	 *     events: [{ type: 'update', path: outputPath, timestamp: Date.now() }]
+	 *   };
+	 * }
+	 * ```
+	 */
+	abstract process(filePath: string): Promise<HmrAction>;
+}

package/src/hmr/hmr.postcss.test.e2e.ts

@@ -0,0 +1,41 @@
+import { test, expect } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const FIXTURE_DIR = resolve(process.cwd(), 'packages/core/__fixtures__/app');
+const TEST_CSS_FILE = resolve(FIXTURE_DIR, 'src/pages/postcss-hmr.css');
+
+test.describe('HMR E2E PostCSS', () => {
+	test('should hot-update processor-owned CSS without a full page reload', async ({ page }) => {
+		const originalCss = readFileSync(TEST_CSS_FILE, 'utf-8');
+		const title = page.locator('.postcss-title').first();
+
+		try {
+			await page.goto('/postcss-hmr', { waitUntil: 'networkidle' });
+			await expect(title).toBeVisible();
+
+			const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
+			expect(initialColor).toBeTruthy();
+			await page.evaluate(() => {
+				(window as typeof window & { __postcssReloadProbe?: string }).__postcssReloadProbe = 'before-change';
+			});
+
+			const modifiedCss = originalCss.replace('.postcss-title {', '.postcss-title {\n\tcolor: rgb(255, 0, 0);');
+
+			await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+
+			await expect
+				.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 10000 })
+				.toBe('rgb(255, 0, 0)');
+
+			await expect(
+				page.evaluate(
+					() => (window as typeof window & { __postcssReloadProbe?: string }).__postcssReloadProbe ?? null,
+				),
+			).resolves.toBe('before-change');
+		} finally {
+			await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+		}
+	});
+});

package/src/hmr/hmr.test.e2e.ts

@@ -0,0 +1,66 @@
+import { test, expect } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+/**
+ * HMR E2E Tests
+ *
+ * True end-to-end tests for Hot Module Replacement using Playwright.
+ * These tests modify actual source files and verify the browser updates.
+ *
+ * Run with: bunx playwright test packages/core/src/hmr/hmr.e2e.test.ts
+ */
+
+const FIXTURE_DIR = resolve(process.cwd(), 'packages/core/__fixtures__/app');
+const TEST_CSS_FILE = resolve(FIXTURE_DIR, 'src/pages/index.css');
+
+test.describe('HMR E2E', () => {
+	test('should load page with .main-title element', async ({ page }) => {
+		await page.goto('/', { waitUntil: 'networkidle' });
+		const title = page.locator('.main-title').first();
+		await expect(title).toBeVisible();
+	});
+
+	test('should connect to HMR WebSocket', async ({ page }) => {
+		const socketPromise = page.waitForEvent('websocket', {
+			predicate: (socket) => socket.url().endsWith('/_hmr'),
+			timeout: 10000,
+		});
+
+		await page.goto('/', { waitUntil: 'networkidle' });
+		const socket = await socketPromise;
+
+		expect(socket.url()).toMatch(/\/_hmr$/);
+	});
+
+	test('should fall back to a full page reload when raw CSS file changes', async ({ page }) => {
+		const originalCss = readFileSync(TEST_CSS_FILE, 'utf-8');
+		const title = page.locator('.main-title').first();
+
+		try {
+			await page.goto('/', { waitUntil: 'networkidle' });
+			await expect(title).toBeVisible();
+
+			const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
+			expect(initialColor).toBeTruthy();
+
+			const modifiedCss = originalCss.replace('.main-title {', '.main-title {\n\tcolor: rgb(255, 0, 0);');
+			const reloadPromise = page.waitForEvent('framenavigated', {
+				predicate: (frame) => frame === page.mainFrame(),
+				timeout: 10000,
+			});
+
+			await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+
+			await reloadPromise;
+			await page.waitForLoadState('networkidle');
+
+			await expect
+				.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 10000 })
+				.toBe('rgb(255, 0, 0)');
+		} finally {
+			await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+		}
+	});
+});

package/src/hmr/strategies/default-hmr-strategy.ts

@@ -0,0 +1,60 @@
+/**
+ * Default HMR Strategy
+ *
+ * Fallback strategy for file types that don't have specialized handling.
+ * Triggers a full page reload to ensure changes are reflected.
+ *
+ * @module
+ */
+
+import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy.ts';
+
+/**
+ * Default fallback strategy for unhandled file types.
+ *
+ * This strategy matches all files and triggers a full page reload.
+ * It has the lowest priority (FALLBACK) and acts as a catch-all when
+ * no other strategy matches the changed file.
+ *
+ * @remarks
+ * This strategy ensures that all file changes result in some action,
+ * even if we don't have specialized handling for that file type.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new DefaultHmrStrategy();
+ * const action = await strategy.process('/path/to/unknown.file');
+ * ```
+ */
+export class DefaultHmrStrategy extends HmrStrategy {
+	readonly type = HmrStrategyType.FALLBACK;
+
+	/**
+	 * Matches all file paths.
+	 *
+	 * @param _filePath - Absolute path to the changed file (unused)
+	 * @returns Always returns true as this is a catch-all strategy
+	 */
+	matches(_filePath: string): boolean {
+		return true;
+	}
+
+	/**
+	 * Processes a file change by triggering a full page reload.
+	 *
+	 * @param filePath - Absolute path to the changed file
+	 * @returns Action to broadcast a reload event
+	 */
+	async process(filePath: string): Promise<HmrAction> {
+		return {
+			type: 'broadcast',
+			events: [
+				{
+					type: 'reload',
+					path: filePath,
+					message: 'fallback-strategy',
+				},
+			],
+		};
+	}
+}