@ecopages/core 0.2.0-alpha.1

package/src/hmr/hmr-strategy.ts

@@ -0,0 +1,172 @@
+import type { ClientBridgeEvent } from '../public-types';
+
+/**
+ * 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 enum 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,
+}
+
+/**
+ * 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'.
+	 * capable of broadcasting multiple events at once.
+	 */
+	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 should be stateless and idempotent. The same file change should always
+ * 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 if 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.test.e2e.d.ts

@@ -0,0 +1 @@
+export {};

package/src/hmr/hmr.test.e2e.js

@@ -0,0 +1,50 @@
+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/index.css");
+const BUILT_CSS_FILE = resolve(FIXTURE_DIR, ".eco/assets/pages/index.css");
+const TEST_URL = "http://localhost:3002";
+test.describe("HMR E2E", () => {
+  test("should load page with .main-title element", async ({ page }) => {
+    await page.goto(TEST_URL, { waitUntil: "networkidle" });
+    const title = page.locator(".main-title").first();
+    await expect(title).toBeVisible();
+  });
+  test("should connect to HMR WebSocket", async ({ page }) => {
+    await page.goto(TEST_URL);
+    const connected = await page.evaluate(async () => {
+      return new Promise((resolve2) => {
+        const ws = new WebSocket("ws://localhost:3002/_hmr");
+        ws.onopen = () => {
+          ws.close();
+          resolve2(true);
+        };
+        ws.onerror = () => resolve2(false);
+        setTimeout(() => resolve2(false), 5e3);
+      });
+    });
+    expect(connected).toBe(true);
+  });
+  test("should reload page when CSS file changes", async ({ page }) => {
+    const originalCss = readFileSync(TEST_CSS_FILE, "utf-8");
+    await page.goto(TEST_URL, { waitUntil: "networkidle" });
+    const initialColor = await page.evaluate(() => {
+      const el = document.querySelector(".main-title");
+      return el ? getComputedStyle(el).color : null;
+    });
+    expect(initialColor).toBeTruthy();
+    const modifiedCss = originalCss.replace(".main-title {", ".main-title {\n	color: rgb(255, 0, 0);");
+    const loadPromise = page.waitForEvent("load", { timeout: 1e4 });
+    await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+    await writeFile(BUILT_CSS_FILE, modifiedCss, { flush: true });
+    await loadPromise;
+    const updatedColor = await page.evaluate(() => {
+      const el = document.querySelector(".main-title");
+      return el ? getComputedStyle(el).color : null;
+    });
+    expect(updatedColor).toBe("rgb(255, 0, 0)");
+    await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+  });
+});

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

@@ -0,0 +1,75 @@
+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');
+const BUILT_CSS_FILE = resolve(FIXTURE_DIR, '.eco/assets/pages/index.css');
+const TEST_URL = 'http://localhost:3002';
+
+test.describe('HMR E2E', () => {
+	test('should load page with .main-title element', async ({ page }) => {
+		await page.goto(TEST_URL, { waitUntil: 'networkidle' });
+		const title = page.locator('.main-title').first();
+		await expect(title).toBeVisible();
+	});
+
+	test('should connect to HMR WebSocket', async ({ page }) => {
+		await page.goto(TEST_URL);
+
+		const connected = await page.evaluate(async () => {
+			return new Promise<boolean>((resolve) => {
+				const ws = new WebSocket('ws://localhost:3002/_hmr');
+				ws.onopen = () => {
+					ws.close();
+					resolve(true);
+				};
+				ws.onerror = () => resolve(false);
+				setTimeout(() => resolve(false), 5000);
+			});
+		});
+
+		expect(connected).toBe(true);
+	});
+
+	test('should reload page when CSS file changes', async ({ page }) => {
+		const originalCss = readFileSync(TEST_CSS_FILE, 'utf-8');
+
+		await page.goto(TEST_URL, { waitUntil: 'networkidle' });
+
+		const initialColor = await page.evaluate(() => {
+			const el = document.querySelector('.main-title');
+			return el ? getComputedStyle(el).color : null;
+		});
+
+		expect(initialColor).toBeTruthy();
+
+		const modifiedCss = originalCss.replace('.main-title {', '.main-title {\n\tcolor: rgb(255, 0, 0);');
+
+		const loadPromise = page.waitForEvent('load', { timeout: 10000 });
+
+		await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+		await writeFile(BUILT_CSS_FILE, modifiedCss, { flush: true });
+
+		await loadPromise;
+
+		const updatedColor = await page.evaluate(() => {
+			const el = document.querySelector('.main-title');
+			return el ? getComputedStyle(el).color : null;
+		});
+
+		expect(updatedColor).toBe('rgb(255, 0, 0)');
+
+		await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+	});
+});

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

@@ -0,0 +1,43 @@
+/**
+ * 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';
+/**
+ * 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 declare 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;
+    /**
+     * 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
+     */
+    process(filePath: string): Promise<HmrAction>;
+}

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

@@ -0,0 +1,34 @@
+import { HmrStrategy, HmrStrategyType } from "../hmr-strategy";
+class DefaultHmrStrategy extends HmrStrategy {
+  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) {
+    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) {
+    return {
+      type: "broadcast",
+      events: [
+        {
+          type: "reload",
+          path: filePath,
+          message: "fallback-strategy"
+        }
+      ]
+    };
+  }
+}
+export {
+  DefaultHmrStrategy
+};

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

package/src/hmr/strategies/js-hmr-strategy.d.ts

@@ -0,0 +1,136 @@
+/**
+ * JavaScript HMR Strategy
+ *
+ * Handles hot module replacement for JavaScript and TypeScript entrypoints.
+ * Bundles files, replaces bare specifiers, and injects HMR boilerplate.
+ *
+ * @module
+ */
+import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+/**
+ * Context interface providing access to HmrManager state.
+ * Required for JsHmrStrategy to access registered entrypoints and configuration.
+ */
+export interface JsHmrContext {
+    /**
+     * Map of registered entrypoints to their output URLs.
+     */
+    getWatchedFiles(): Map<string, string>;
+    /**
+     * Map of bare specifiers to vendor URLs for import resolution.
+     */
+    getSpecifierMap(): Map<string, string>;
+    /**
+     * Returns entrypoints impacted by a changed dependency path.
+     *
+     * @remarks
+     * This hook is currently provided by the Node HMR manager where dependency
+     * graph metadata is extracted from the Node/esbuild build adapter.
+     */
+    getDependencyEntrypoints?(filePath: string): Set<string>;
+    /**
+     * Stores latest dependency set for an entrypoint.
+     *
+     * @remarks
+     * This hook is currently used only by the Node HMR manager to maintain a
+     * reverse invalidation index. Runtimes that do not provide it keep rebuild-all
+     * fallback semantics.
+     */
+    setEntrypointDependencies?(entrypointPath: string, dependencies: string[]): void;
+    /**
+     * Directory where HMR bundles are written.
+     */
+    getDistDir(): string;
+    /**
+     * Build plugins to use during bundling.
+     */
+    getPlugins(): EcoBuildPlugin[];
+    /**
+     * Absolute path to the source directory.
+     */
+    getSrcDir(): string;
+}
+/**
+ * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
+ *
+ * This strategy rebuilds all registered entrypoints when any file changes,
+ * as we don't currently track dependencies. This is safe but inefficient.
+ *
+ * The processing steps are:
+ * 1. Check if any entrypoints are registered
+ * 2. Rebuild all entrypoints (the changed file could be a dependency)
+ * 3. Replace bare specifiers with vendor URLs
+ * 4. Inject generic HMR boilerplate
+ * 5. Broadcast update events for each rebuilt entrypoint
+ *
+ * @remarks
+ * Future enhancement: Track dependencies using Bun's transpiler API to only
+ * rebuild affected entrypoints instead of all of them.
+ *
+ * @see https://bun.sh/docs/runtime/transpiler
+ *
+ * @example
+ * ```typescript
+ * const context = {
+ *   getWatchedFiles: () => watchedFilesMap,
+ *   getSpecifierMap: () => specifierMap,
+ *   getDistDir: () => '/path/to/dist/_hmr',
+ *   getPlugins: () => [],
+ *   getSrcDir: () => '/path/to/src'
+ * };
+ * const strategy = new JsHmrStrategy(context);
+ * ```
+ */
+export declare class JsHmrStrategy extends HmrStrategy {
+    private context;
+    readonly type = HmrStrategyType.SCRIPT;
+    constructor(context: JsHmrContext);
+    /**
+     * Determines if the file is a JS/TS file that could affect registered entrypoints.
+     *
+     * Matches if:
+     * 1. There are registered entrypoints to rebuild
+     * 2. The changed file is a JS/TS file in the src directory
+     *
+     * @param filePath - Absolute path to the changed file
+     * @returns True if this file should trigger entrypoint rebuilds
+     */
+    matches(filePath: string): boolean;
+    /**
+     * Processes a file change by rebuilding affected entrypoints.
+     *
+     * @param filePath - Absolute path to the changed file
+     *
+     * @remarks
+     * If runtime-specific dependency graph hooks are unavailable, this strategy
+     * falls back to rebuilding all watched entrypoints.
+     * @returns Action to broadcast update events
+     */
+    process(filePath: string): Promise<HmrAction>;
+    /**
+     * Bundles a single entrypoint and processes the output.
+     *
+     * @param entrypointPath - Absolute path to the source file
+     * @param outputUrl - URL path for the bundled file
+     * @returns True if bundling was successful
+     */
+    private bundleEntrypoint;
+    /**
+     * Processes bundled output by replacing specifiers and injecting HMR code.
+     *
+     * @param filepath - Path to the bundled output file
+     * @param url - URL path for the bundled file
+     * @returns True if processing was successful and update should be broadcast
+     */
+    private processOutput;
+    /**
+     * Replaces bare specifiers with vendor URLs.
+     *
+     * Handles both static imports and dynamic imports.
+     *
+     * @param code - The bundled code to transform
+     * @returns The transformed code with vendor URLs
+     */
+    private replaceBareSpecifiers;
+}