@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

package/src/hmr/hmr-strategy.js

@@ -1,44 +1,115 @@
-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
+/**
+ * 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,
 };
-class HmrStrategy {
-  /**
-   * Optional offset to fine-tune priority within the same category.
-   * Useful when multiple strategies share the same type.
-   *
-   * @defaultValue 0
-   */
-  priorityOffset = 0;
-  /**
-   * Computed priority for strategy selection.
-   * Higher values are evaluated first.
-   *
-   * @returns The sum of the strategy type and priority offset
-   */
-  get priority() {
-    return this.type + this.priorityOffset;
-  }
+/**
+ * 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 class HmrStrategy {
+    /**
+     * Optional offset to fine-tune priority within the same category.
+     * Useful when multiple strategies share the same type.
+     *
+     * @defaultValue 0
+     */
+    priorityOffset = 0;
+    /**
+     * Computed priority for strategy selection.
+     * Higher values are evaluated first.
+     *
+     * @returns The sum of the strategy type and priority offset
+     */
+    get priority() {
+        return this.type + this.priorityOffset;
+    }
+    /**
+     * Returns whether this strategy supplies dev-transform plugins for a source module.
+     *
+     * @remarks
+     * Used by {@link DevTransformBundler} to select integration-owned plugins for any
+     * module in the per-file ESM graph (pages and imported children). File-change
+     * dispatch continues to use {@link matches}.
+     */
+    ownsDevTransformEntrypoint(_sourcePath) {
+        return false;
+    }
 }
-export {
-  HmrStrategy,
-  HmrStrategyType
-};

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

@@ -1,34 +1,56 @@
-import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
-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"
-        }
-      ]
-    };
-  }
+/**
+ * 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 } from '../hmr-strategy.js';
+/**
+ * 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 {
+    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/js-hmr-strategy.d.ts

@@ -2,133 +2,42 @@
  * JavaScript HMR Strategy
  *
  * Handles hot module replacement for JavaScript and TypeScript entrypoints.
- * Bundles files, inspects the emitted output, and decides whether the browser
- * can hot-accept the change or must reload.
+ * Invalidates dev-transform modules and decides whether the browser can hot-accept
+ * the change or must reload.
  *
  * @module
  */
 import { HmrStrategy, type HmrAction } from '../hmr-strategy.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
-import type { BrowserBundleExecutor } from '../../services/assets/browser-bundle.service.js';
+import type { HmrRegisteredEntrypointsContext } from '../hmr-registered-entrypoints-context.js';
 import type { EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.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.
-     */
+export interface JsHmrContext extends HmrRegisteredEntrypointsContext {
     getWatchedFiles(): Map<string, string>;
     getEntrypointDependencyGraph(): EntrypointDependencyGraph;
-    /**
-     * Directory where HMR bundles are written.
-     */
-    getDistDir(): string;
-    /**
-     * Build plugins to use during bundling.
-     */
-    getPlugins(): EcoBuildPlugin[];
-    /**
-     * Absolute path to the source directory.
-     */
     getSrcDir(): string;
-    /**
-     * Absolute path to the pages directory.
-     */
     getPagesDir(): string;
-    /**
-     * Absolute path to the layouts directory.
-     */
     getLayoutsDir(): string;
-    /**
-     * All configured route-template extensions across integrations.
-     */
     getTemplateExtensions(): string[];
     /**
-     * Browser bundler used to rebuild changed entrypoints.
-     */
-    getBrowserBundleService(): BrowserBundleExecutor;
-    /**
-     * Returns whether a watched entrypoint should be rebuilt by the generic JS strategy.
-     *
      * @remarks
      * Integrations with higher-priority HMR strategies can use this to keep the
      * generic JS strategy from overwriting their emitted entrypoints when a shared
      * dependency changes.
      */
     shouldProcessEntrypoint?(entrypointPath: string): boolean;
+    invalidateDevTransformSource?(sourcePath: string): void;
+    consumeRegisteredScriptReloadRequired?(filePath: string): boolean;
 }
 /**
  * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
- *
- * The processing steps are:
- * 1. Check if any entrypoints are registered
- * 2. Rebuild impacted entrypoints, or all watched entrypoints when no runtime
- *    dependency graph is available
- * 3. Emit rebuilt entrypoint bundles for browser delivery
- * 4. Inject generic HMR boilerplate
- * 5. Broadcast update events for each rebuilt entrypoint
- *
- * @remarks
- * Node can provide dependency-graph metadata, so this strategy can rebuild only
- * the entrypoints impacted by a changed dependency. Runtimes that do not expose
- * that metadata intentionally keep the rebuild-all fallback.
- *
- * @see https://bun.sh/docs/runtime/transpiler
- *
- * @example
- * ```typescript
- * const context = {
- *   getWatchedFiles: () => watchedFilesMap,
- *   getDistDir: () => '/path/to/dist/_hmr',
- *   getPlugins: () => [],
- *   getSrcDir: () => '/path/to/src'
- * };
- * const strategy = new JsHmrStrategy(context);
- * ```
  */
 export declare class JsHmrStrategy extends HmrStrategy {
     readonly type: 25;
     private context;
     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.
-     * When multiple entrypoints are impacted they are bundled in a single
-     * invocation to share AST parsing and chunk deduplication.
-     * @returns Action to broadcast update events
-     */
     process(filePath: string): Promise<HmrAction>;
-    /**
-     * Bundles one or more entrypoints in a single build invocation.
-     * Uses the source directory as the output base so that the directory structure
-     * is preserved under the HMR dist folder.
-     */
-    private bundleEntrypoints;
-    /**
-     * Processes bundled output and determines whether the browser can hot-accept
-     * the update or must fall back to a full reload.
-     *
-     * @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;
 }

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

@@ -1,173 +1,113 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
-import { appLogger } from "../../global/app-logger.js";
-class JsHmrStrategy extends HmrStrategy {
-  type = HmrStrategyType.SCRIPT;
-  context;
-  constructor(context) {
-    super();
-    this.context = context;
-  }
-  /**
-   * 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) {
-    const watchedFiles = this.context.getWatchedFiles();
-    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
-    const isInSrc = filePath.startsWith(this.context.getSrcDir());
-    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
-    if (watchedFiles.size === 0) {
-      return false;
+/**
+ * JavaScript HMR Strategy
+ *
+ * Handles hot module replacement for JavaScript and TypeScript entrypoints.
+ * Invalidates dev-transform modules and decides whether the browser can hot-accept
+ * the change or must reload.
+ *
+ * @module
+ */
+import path from 'node:path';
+import { HmrStrategy, HmrStrategyType } from '../hmr-strategy.js';
+import { appLogger } from '../../global/app-logger.js';
+import { isRegisteredDevTransformEntrypoint, isRegisteredScriptEntrypoint } from '../hmr-entrypoint-output.js';
+import { isDevTransformModuleUrl } from '../hmr-asset-paths.js';
+/**
+ * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
+ */
+export class JsHmrStrategy extends HmrStrategy {
+    type = HmrStrategyType.SCRIPT;
+    context;
+    constructor(context) {
+        super();
+        this.context = context;
     }
-    if (!isJsTs || !isInSrc) {
-      return false;
-    }
-    if (isIntegrationTemplate) {
-      return false;
-    }
-    if (watchedFiles.has(filePath)) {
-      return true;
-    }
-    return true;
-  }
-  /**
-   * 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.
-   * When multiple entrypoints are impacted they are bundled in a single
-   * invocation to share AST parsing and chunk deduplication.
-   * @returns Action to broadcast update events
-   */
-  async process(filePath) {
-    appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
-    const watchedFiles = this.context.getWatchedFiles();
-    if (watchedFiles.size === 0) {
-      appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
-      return { type: "none" };
-    }
-    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
-    const hasDependencyHit = dependencyHits.size > 0;
-    const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint)) : Array.from(watchedFiles.keys());
-    const buildableEntrypoints = impactedEntrypoints.filter(
-      (entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true
-    );
-    if (!hasDependencyHit) {
-      appLogger.debug("[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints");
-    }
-    if (buildableEntrypoints.length === 0) {
-      return { type: "none" };
-    }
-    const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
-    if (!buildResult.success) {
-      return { type: "none" };
-    }
-    const updates = [];
-    let reloadRequired = false;
-    for (const entrypoint of buildableEntrypoints) {
-      const outputUrl = watchedFiles.get(entrypoint);
-      if (!outputUrl) continue;
-      if (buildResult.dependencies) {
-        const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
-        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
-      }
-      const srcDir = this.context.getSrcDir();
-      const relativePath = path.relative(srcDir, entrypoint);
-      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
-      const result = await this.processOutput(outputPath, outputUrl);
-      if (result.success) {
-        updates.push(outputUrl);
-        if (result.requiresReload) {
-          reloadRequired = true;
+    matches(filePath) {
+        const watchedFiles = this.context.getWatchedFiles();
+        const resolvedPath = path.resolve(filePath);
+        const isJsTs = /\.(ts|tsx|js|jsx)$/.test(resolvedPath);
+        const srcDir = path.resolve(this.context.getSrcDir());
+        const isInSrc = resolvedPath.startsWith(`${srcDir}${path.sep}`) || resolvedPath === srcDir;
+        const isIntegrationTemplate = this.context
+            .getTemplateExtensions()
+            .some((extension) => resolvedPath.endsWith(extension));
+        if (watchedFiles.size === 0) {
+            return false;
         }
-      }
-    }
-    if (updates.length > 0) {
-      if (reloadRequired) {
-        appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
-        return {
-          type: "broadcast",
-          events: [{ type: "reload" }]
-        };
-      }
-      return {
-        type: "broadcast",
-        events: updates.map((p) => ({
-          type: "update",
-          path: p,
-          timestamp: Date.now()
-        }))
-      };
-    }
-    return { type: "none" };
-  }
-  /**
-   * Bundles one or more entrypoints in a single build invocation.
-   * Uses the source directory as the output base so that the directory structure
-   * is preserved under the HMR dist folder.
-   */
-  async bundleEntrypoints(entrypoints) {
-    try {
-      const result = await this.context.getBrowserBundleService().bundle({
-        profile: "hmr-entrypoint",
-        entrypoints,
-        outdir: this.context.getDistDir(),
-        outbase: this.context.getSrcDir(),
-        naming: "[dir]/[name]",
-        plugins: this.context.getPlugins(),
-        minify: false
-      });
-      if (!result.success) {
-        appLogger.error("[JsHmrStrategy] Batched build failed:", result.logs);
-        return { success: false };
-      }
-      const dependencies = /* @__PURE__ */ new Map();
-      if (result.dependencyGraph?.entrypoints) {
-        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
-          dependencies.set(path.resolve(entrypoint), deps);
+        if (!isJsTs || !isInSrc) {
+            return false;
         }
-      }
-      return { success: true, dependencies };
-    } catch (error) {
-      appLogger.error("[JsHmrStrategy] Error in batched build:", error);
-      return { success: false };
+        if (watchedFiles.has(resolvedPath)) {
+            return true;
+        }
+        if (isIntegrationTemplate) {
+            return false;
+        }
+        return true;
     }
-  }
-  /**
-   * Processes bundled output and determines whether the browser can hot-accept
-   * the update or must fall back to a full reload.
-   *
-   * @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
-   */
-  async processOutput(filepath, url) {
-    try {
-      const code = await fileSystem.readFile(filepath);
-      if (code.includes("/* [ecopages] hmr */")) {
-        return { success: true, requiresReload: !code.includes("import.meta.hot.accept") };
-      }
-      appLogger.debug(`[JsHmrStrategy] Processed ${url}`);
-      const hasHmrAccept = code.includes("import.meta.hot.accept");
-      return { success: true, requiresReload: !hasHmrAccept };
-    } catch (error) {
-      appLogger.error(`[JsHmrStrategy] Error processing output for ${url}:`, error);
-      return { success: false, requiresReload: false };
+    async process(filePath) {
+        appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
+        const watchedFiles = this.context.getWatchedFiles();
+        const resolvedChanged = path.resolve(filePath);
+        const registeredEntrypoints = this.context.getRegisteredEntrypoints();
+        const isRegisteredEntrypointEdit = isRegisteredDevTransformEntrypoint(registeredEntrypoints, resolvedChanged);
+        if (watchedFiles.size === 0) {
+            appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
+            return { type: 'none' };
+        }
+        const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
+        const hasDependencyHit = dependencyHits.size > 0;
+        const impactedEntrypoints = isRegisteredEntrypointEdit
+            ? [resolvedChanged]
+            : hasDependencyHit
+                ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(path.resolve(entrypoint)))
+                : Array.from(watchedFiles.keys());
+        const buildableEntrypoints = impactedEntrypoints.filter((entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true);
+        if (!hasDependencyHit && !isRegisteredEntrypointEdit) {
+            appLogger.debug('[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints');
+        }
+        if (buildableEntrypoints.length === 0) {
+            return { type: 'none' };
+        }
+        const devTransformUpdates = [];
+        let devTransformReloadRequired = false;
+        for (const entrypoint of buildableEntrypoints) {
+            const resolvedEntrypoint = path.resolve(entrypoint);
+            const outputUrl = watchedFiles.get(resolvedEntrypoint);
+            if (!outputUrl || !isDevTransformModuleUrl(outputUrl)) {
+                appLogger.debug(`[JsHmrStrategy] Skipping non-dev-transform entrypoint ${resolvedEntrypoint}: ${outputUrl ?? 'unregistered'}`);
+                continue;
+            }
+            this.context.invalidateDevTransformSource?.(resolvedEntrypoint);
+            if (isRegisteredScriptEntrypoint(registeredEntrypoints, resolvedEntrypoint)) {
+                if (this.context.consumeRegisteredScriptReloadRequired?.(resolvedEntrypoint)) {
+                    devTransformReloadRequired = true;
+                }
+                else {
+                    devTransformUpdates.push(outputUrl);
+                }
+            }
+            else {
+                devTransformUpdates.push(outputUrl);
+            }
+        }
+        if (devTransformReloadRequired) {
+            appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
+            return {
+                type: 'broadcast',
+                events: [{ type: 'reload' }],
+            };
+        }
+        if (devTransformUpdates.length > 0) {
+            return {
+                type: 'broadcast',
+                events: devTransformUpdates.map((p) => ({
+                    type: 'update',
+                    path: p,
+                    timestamp: Date.now(),
+                })),
+            };
+        }
+        return { type: 'none' };
     }
-  }
 }
-export {
-  JsHmrStrategy
-};