@addfox/rsbuild-plugin-extension-hmr 0.1.1-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 addfox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @addfox/rsbuild-plugin-extension-hmr
+
+[中文](README-zh_CN.md) | English
+
+---
+
+Rsbuild plugin: in dev, waits for dist then launches the browser (Chrome/Edge/Brave/Vivaldi/Opera/Santa/Firefox) and enables HMR reload via WebSocket. Used by CLI dev command.
+
+- Options: distPath, browser, chromePath/edgePath/bravePath/vivaldiPath/operaPath/santaPath/firefoxPath, wsPort, enableReload, persist
+- **Chromium launch**: uses `chrome-launcher` with CDP `Extensions.loadUnpacked` for native extension loading; falls back to `--load-extension` on older Chrome versions
+- **Firefox launch**: uses [web-ext run](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-run) (`--target=firefox-desktop`)
+- **Reload manager**: a helper extension that listens to WebSocket and toggles (disable+enable) dev extensions on rebuild
+- **Browser path registry**: all browser default paths are managed via a single `BROWSER_DEFAULT_PATHS` map; user can override via `config.launch.*`
+- Injected by pipeline from config.launch and CLI `-b`/`--browser`

package/dist/browser/index.d.ts

@@ -0,0 +1,4 @@
+export { getLaunchPathFromOptions, buildDefaultPaths, getBrowserPath, isChromiumBrowser, type LaunchPathOptions, } from "./paths";
+export { runChromiumRunner, type ChromiumRunnerOptions, } from "./runner";
+export { launchBrowser, launchBrowserOnly, cleanup, registerCleanupHandlers, statsHasErrors, setBrowserLaunched, getBrowserLaunched, type LaunchContext, type HmrPluginOptionsForLaunch, type LaunchOnlyOptions, type ChromiumRunnerOverride, } from "./launcher";
+export { getCacheTempRoot, getChromiumUserDataDir, getReloadManagerPath, findExistingReloadManager, ensureDistReady, } from "../manager/extension";

package/dist/browser/launcher.d.ts

@@ -0,0 +1,55 @@
+import type { LaunchTarget } from "@addfox/core";
+import type { ChromiumRunnerOptions } from "./runner";
+import { type LaunchPathOptions } from "./paths";
+export type ChromiumRunnerOverride = (opts: ChromiumRunnerOptions) => Promise<{
+    exit: () => Promise<void>;
+}>;
+export interface LaunchContext {
+    distPath: string;
+    browser: LaunchTarget;
+    pathOpts: LaunchPathOptions;
+    cache: boolean;
+    enableReload: boolean;
+    wsPort: number;
+    chromiumRunnerOverride?: ChromiumRunnerOverride;
+    ensureDistReadyOverride?: (distPath: string) => Promise<boolean>;
+    getBrowserPathOverride?: (b: LaunchTarget, o: LaunchPathOptions) => string | null;
+    onBrowserExit: () => void;
+    debug?: boolean;
+    root?: string;
+    outputRoot?: string;
+}
+export declare function cleanup(): Promise<void>;
+export declare function registerCleanupHandlers(): void;
+export declare function launchBrowserCore(ctx: LaunchContext): Promise<void>;
+export interface HmrPluginOptionsForLaunch {
+    distPath: string;
+    browser?: LaunchTarget;
+    cache?: boolean;
+    wsPort?: number;
+    enableReload?: boolean;
+    debug?: boolean;
+    root?: string;
+    outputRoot?: string;
+    chromePath?: string;
+    chromiumPath?: string;
+    edgePath?: string;
+    bravePath?: string;
+    vivaldiPath?: string;
+    operaPath?: string;
+    santaPath?: string;
+    arcPath?: string;
+    yandexPath?: string;
+    browserosPath?: string;
+    customPath?: string;
+    firefoxPath?: string;
+}
+export declare function launchBrowser(options: HmrPluginOptionsForLaunch, chromiumRunnerOverride?: ChromiumRunnerOverride, ensureDistReadyOverride?: (distPath: string) => Promise<boolean>, getBrowserPathOverride?: (b: LaunchTarget, o: LaunchPathOptions) => string | null): Promise<void>;
+export declare function setBrowserLaunched(value: boolean): void;
+export declare function getBrowserLaunched(): boolean;
+export declare function statsHasErrors(stats: unknown): boolean;
+export { getReloadManagerPath, getChromiumUserDataDir, getCacheRoot, getBrowserProfileDir, 
+/** @deprecated Use getCacheRoot/getBrowserProfileDir instead */
+getCacheTempRoot, findExistingReloadManager, ensureDistReady, } from "../manager/extension";
+export declare function launchBrowserOnly(options: LaunchOnlyOptions, chromiumRunnerOverride?: ChromiumRunnerOverride): Promise<void>;
+export type LaunchOnlyOptions = Pick<HmrPluginOptionsForLaunch, "distPath" | "browser" | "chromePath" | "chromiumPath" | "edgePath" | "bravePath" | "vivaldiPath" | "operaPath" | "santaPath" | "arcPath" | "yandexPath" | "browserosPath" | "customPath" | "firefoxPath" | "cache" | "outputRoot" | "debug" | "enableReload">;

package/dist/browser/paths.d.ts

@@ -0,0 +1,6 @@
+import type { LaunchTarget, ChromiumLaunchTarget } from "@addfox/core";
+export type LaunchPathOptions = Pick<Record<string, string | undefined>, "chromePath" | "chromiumPath" | "edgePath" | "bravePath" | "vivaldiPath" | "operaPath" | "santaPath" | "arcPath" | "yandexPath" | "browserosPath" | "customPath" | "firefoxPath">;
+export declare function getLaunchPathFromOptions(browser: LaunchTarget, options: LaunchPathOptions): string | undefined;
+export declare function buildDefaultPaths(browser: LaunchTarget, platform: string): string[] | undefined;
+export declare function getBrowserPath(browser: LaunchTarget, options: LaunchPathOptions): string | null;
+export declare function isChromiumBrowser(browser: LaunchTarget): browser is ChromiumLaunchTarget;

package/dist/browser/runner.d.ts

@@ -0,0 +1,12 @@
+export type ChromiumRunnerOptions = {
+    chromePath: string;
+    extensions: string[];
+    startUrl?: string;
+    userDataDir?: string;
+    args?: string[];
+    verbose?: boolean;
+    onExit?: () => void;
+};
+export declare function runChromiumRunner(options: ChromiumRunnerOptions): Promise<{
+    exit: () => Promise<void>;
+}>;

package/dist/browser/web-ext-console-stream-hook.d.ts

@@ -0,0 +1,7 @@
+export type WebExtConsoleStreamHookUninstall = () => void;
+/**
+ * Wraps web-ext's pino `ConsoleStream.write` so CLI line-prefixing can tag [Web-ext] at the real
+ * output source (not string matching). Idempotent while active.
+ */
+export declare function installWebExtConsoleStreamHook(): Promise<void>;
+export declare function removeWebExtConsoleStreamHook(): void;

package/dist/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Entry names and HMR snippets used across the HMR plugin.
+ * RELOAD_MANAGER_ENTRY_NAMES comes from @addfox/core (single source of truth).
+ */
+/** Entry names that require chrome.runtime.reload() when changed (background). */
+export declare const RELOAD_ENTRY_NAMES: Set<string>;
+/** Entry names injected into pages; when changed, reload manager refreshes active tab. */
+export declare const CONTENT_ENTRY_NAMES: Set<string>;
+/** Injected at top of entry module for precise identification; only content/background. */
+export declare const ADDFOX_ENTRY_TAG_PREFIX = "/* addfox-entry:";
+/** Build entry tag comment for a given entry name (content/background). Used for precise entry identification in built output. */
+export declare function getEntryTag(entryName: string): string;
+/** Prepended to content/background entry modules: force full invalidation so reload is via reloadManager only. */
+export declare const HMR_INVALIDATE_PREPEND = "if(typeof module!=='undefined'&&module.hot){module.hot.invalidate();}\n";

package/dist/hmr/cleanup.d.ts

@@ -0,0 +1,3 @@
+export declare function collectHotUpdateAssetNames(statsList: unknown[]): Set<string>;
+export declare function removeStaleHotUpdateFiles(distPath: string, keepNames: Set<string>): Promise<void>;
+export declare function clearOutdatedHotUpdateFiles(distPath: string, stats: unknown): Promise<void>;

package/dist/hmr/disable.d.ts

@@ -0,0 +1,10 @@
+import type { ReloadManagerEntry } from "@addfox/core";
+export declare function normalizePathForCompare(p: string): string;
+/** Clear the path cache (useful for testing or memory management) */
+export declare function clearPathCache(): void;
+/**
+ * Transforms content/background entry modules:
+ * - Injects entry tag comment (addfox-entry:content / addfox-entry:background) at top when entries have names.
+ * - Prepends module.hot.invalidate() so reload is via reloadManager only.
+ */
+export declare function transformCodeToDisableHmr(resourcePath: string, entriesOrPaths: ReloadManagerEntry[] | string[], code: string): string;

package/dist/hmr/index.d.ts

@@ -0,0 +1,4 @@
+export { transformCodeToDisableHmr, normalizePathForCompare, clearPathCache, } from "./disable";
+export { clearOutdatedHotUpdateFiles, collectHotUpdateAssetNames, removeStaleHotUpdateFiles, } from "./cleanup";
+export { createHmrRspackPlugin, getLastCompiler, getModifiedFilesFromCompiler, } from "./rspack-plugin";
+export { getReloadManagerDecision, getReloadKindFromDecision, isContentChanged, getCompilationFromStats, getEntrypointSignature, getEntriesSignature, getReloadEntriesSignature, getContentEntriesSignature, getEntryToModulePaths, getEntriesForFile, type ReloadManagerDecision, type ReloadKind, } from "./scope";

package/dist/hmr/rspack-plugin.d.ts

@@ -0,0 +1,16 @@
+import type { Compiler } from "@rspack/core";
+import type { HmrPluginOptions, HmrPluginTestDeps } from "../types";
+export declare function getLastCompiler(): Compiler | null;
+/**
+ * Collects modified file paths from compiler:
+ * - Prefers compiler.modifiedFiles when available (Rspack >= 0.5)
+ * - Falls back to watchFileSystem.watcher.mtimes for older versions
+ */
+export declare function getModifiedFilesFromCompiler(compiler: Compiler | null): Set<string>;
+/**
+ * Creates the HMR Rspack plugin that handles browser launch on first successful compilation.
+ */
+export declare function createHmrRspackPlugin(options: HmrPluginOptions, testDeps?: HmrPluginTestDeps): {
+    name: string;
+    apply(compiler: Compiler): void;
+};

package/dist/hmr/scope.d.ts

@@ -0,0 +1,63 @@
+type AssetLike = {
+    filename?: string;
+    info?: {
+        contenthash?: string[];
+        chunkhash?: string[];
+    };
+};
+type ChunkLike = {
+    id?: string;
+    name?: string;
+    hash?: string;
+};
+type EntrypointLike = {
+    name?: string;
+    chunks?: ReadonlyArray<ChunkLike>;
+    getFiles?: () => ReadonlyArray<string>;
+};
+type CompilationLike = {
+    entrypoints?: ReadonlyMap<string, EntrypointLike>;
+    getAsset?: (name: string) => AssetLike | void;
+    getAssets?: () => ReadonlyArray<AssetLike>;
+    getStats?: () => {
+        toJson: (opts?: unknown) => unknown;
+    };
+};
+export interface ReloadManagerDecision {
+    /** True only when content or background entry output actually changed (precise). */
+    shouldNotify: boolean;
+    /** True when content entry changed (for toggle-extension-refresh-page). */
+    contentChanged: boolean;
+    /** True when background entry changed (for reload-extension). */
+    backgroundChanged: boolean;
+}
+export type ReloadKind = "reload-extension" | "toggle-extension" | "toggle-extension-refresh-page";
+export declare function getCompilationFromStats(stats: unknown): CompilationLike | null;
+export declare function getEntrypointSignature(entrypoint: EntrypointLike | undefined): string | null;
+export declare function getEntriesSignature(compilation: CompilationLike, entryNames: Set<string>): string | null;
+type EntryToPaths = Map<string, Set<string>>;
+export declare function getEntryToModulePaths(stats: unknown): EntryToPaths;
+/** Which entry names contain this file path (using path normalization / endsWith). */
+export declare function getEntriesForFile(entryToPaths: EntryToPaths, filePath: string): string[];
+/**
+ * Single place to decide reloadManager WS notification and content-refresh.
+ * Extension.js-style: when compiler.modifiedFiles is available, only notify if a modified file
+ * belongs to content/background chunk. Otherwise fall back to signature comparison.
+ */
+export declare function getReloadManagerDecision(stats: unknown, context?: {
+    compiler?: {
+        modifiedFiles?: ReadonlySet<string>;
+    };
+}): ReloadManagerDecision;
+/**
+ * Choose reload kind from decision and config.
+ * - backgroundChanged → reload-extension (browser reload API).
+ * - contentChanged + autoRefreshContentPage → toggle-extension-refresh-page (toggle + refresh current page).
+ * - else → toggle-extension (toggle only).
+ */
+export declare function getReloadKindFromDecision(contentChanged: boolean, backgroundChanged: boolean, autoRefreshContentPage: boolean): ReloadKind;
+/** True when content entry signature changed (uses same state as getReloadManagerDecision). */
+export declare function isContentChanged(stats: unknown): boolean;
+export declare function getReloadEntriesSignature(stats: unknown): string | null;
+export declare function getContentEntriesSignature(stats: unknown): string | null;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @addfox/rsbuild-plugin-extension-hmr
+ *
+ * Dev mode: launch browser, WebSocket reload manager, and precise HMR/liveReload
+ * control for content/background entries (reload via WS only).
+ */
+import type { RsbuildPlugin } from "@rsbuild/core";
+import type { HmrPluginOptions, HmrPluginTestDeps } from "./types";
+export type { HmrPluginOptions, HmrPluginTestDeps } from "./types";
+export { RELOAD_ENTRY_NAMES, CONTENT_ENTRY_NAMES, getEntryTag } from "./constants";
+export { clearOutdatedHotUpdateFiles } from "./hmr/cleanup";
+export { getLaunchPathFromOptions, buildDefaultPaths, getBrowserPath, isChromiumBrowser } from "./browser/paths";
+export type { LaunchPathOptions } from "./browser/paths";
+export { startWebSocketServer, notifyReload } from "./server/ws-server";
+export type { ExtensionErrorPayload, DebugServerOpts, WsServerMode } from "./server/ws-server";
+export { getCompilationFromStats, getEntrypointSignature, getEntriesSignature, getReloadEntriesSignature, getContentEntriesSignature, getReloadManagerDecision, getReloadKindFromDecision, isContentChanged, getEntryToModulePaths, getEntriesForFile, } from "./hmr/scope";
+export type { ReloadManagerDecision, ReloadKind } from "./hmr/scope";
+export { normalizePathForCompare } from "./hmr/disable";
+export { getCacheRoot, getBrowserProfileDir, 
+/** @deprecated Use getCacheRoot/getBrowserProfileDir instead */
+getCacheTempRoot, getChromiumUserDataDir, getReloadManagerPath, findExistingReloadManager, ensureDistReady, } from "./manager/extension";
+export { launchBrowser, launchBrowserOnly, cleanup, registerCleanupHandlers, statsHasErrors, } from "./browser/launcher";
+export type { LaunchOnlyOptions, ChromiumRunnerOverride } from "./browser/launcher";
+export { createTestWsServer } from "./server/test-server";
+export { createHmrRspackPlugin } from "./hmr/rspack-plugin";
+/**
+ * Rsbuild plugin: in dev mode launches browser after first compile;
+ * notifies reload only when content or background entry (or their dependencies) changed;
+ * disables HMR/liveReload for content/background via transform and optional entry tag injection.
+ */
+export declare function hmrPlugin(options: HmrPluginOptions, testDeps?: HmrPluginTestDeps): RsbuildPlugin;