@ecopages/core 0.2.0-beta.30 → 0.2.0-beta.32

package/src/hmr/hmr-strategy.js

@@ -1,63 +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;
-  }
-  /**
-   * Returns whether this strategy owns cold registration for the entrypoint.
-   *
-   * @remarks
-   * Registration dispatch uses only integration strategies that claim the
-   * entrypoint. File-change dispatch continues to use {@link matches}.
-   */
-  canEmitEntrypoint(_entrypointPath) {
-    return false;
-  }
-  /**
-   * Materializes one integration-owned HMR entrypoint during registration.
-   *
-   * @remarks
-   * Must write the canonical output path and must not broadcast client events.
-   */
-  async emitEntrypoint(_entrypointPath, _outputPath) {
-    return;
-  }
+/**
+ * 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,131 +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 { 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;
-    /**
-     * 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
-     * 3. Registered entrypoints always match, even when they share an integration template extension
-     *
-     * @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>;
-    private resolveEntrypointOutputPath;
-    private removeStaleEntrypointOutput;
-    /**
-     * 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;
 }