@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

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

@@ -1,162 +0,0 @@
-/**
- * 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[handlerPaths.length - 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

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

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

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

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

@@ -1,60 +0,0 @@
-/**
- * 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',
-				},
-			],
-		};
-	}
-}