@utoo/web 1.2.8 → 1.3.0-rc.2

package/README.md

@@ -9,7 +9,8 @@
 - 📂 **Real File System**: Uses Origin Private File System (OPFS) for a Node.js-like file system experience.
 - 📦 **Browser Dependency Resolution**: Resolve dependencies directly from `package.json` without needing a pre-existing lock file. Supports custom registries (npm, npmmirror, private registries).
 - 🌐 **Browser-based Bundling**: Run the Utoo bundler directly in the browser.
-- 🔌 **Webpack Compatibility**: Supports a subset of Webpack configurations in the browser. See [Features List](../pack/docs/features-list.md) for details.
+- � **Hot Module Replacement (HMR)**: Full HMR support in the browser via MessagePort communication with preview iframes.
+- �🔌 **Webpack Compatibility**: Supports a subset of Webpack configurations in the browser. See [Features List](../pack/docs/features-list.md) for details.
 - 🔄 **Webpack Loaders**: Compatible with standard Webpack loaders (css-loader, style-loader, etc.).
 - 🎨 **PostCSS & Tailwind**: Support for PostCSS and Tailwind CSS processing.
 

package/esm/hmr/HmrServer.d.ts

@@ -0,0 +1,89 @@
+/**
+ * HmrServer - Simulates a WebSocket server using MessagePort for HMR communication.
+ *
+ * This class manages HMR connections with preview iframes, forwarding Turbopack
+ * HMR events from the main project to the preview iframe's HMR client.
+ *
+ * Architecture:
+ * - Main Thread (Project) -> HmrServer -> MessagePort -> Preview Iframe (HMR Client)
+ */
+import type { HMR_ACTION_TYPES, TurbopackUpdate } from "@utoo/pack-shared";
+export interface HmrServerOptions {
+    /** Session ID for this HMR server instance */
+    sessionId?: number;
+    /** Callback when a client subscribes to an HMR path */
+    onSubscribe?: (path: string, client: HmrClient) => void;
+    /** Callback when a client unsubscribes from an HMR path */
+    onUnsubscribe?: (path: string, client: HmrClient) => void;
+}
+export interface HmrClient {
+    /** Unique client ID */
+    id: string;
+    /** The MessagePort for this client */
+    port: MessagePort;
+    /** Send a message to this client */
+    send(message: HMR_ACTION_TYPES): void;
+    /** Close the connection to this client */
+    close(): void;
+}
+/**
+ * HmrServer manages HMR connections with preview iframes.
+ */
+export declare class HmrServer {
+    private clients;
+    private subscriptions;
+    private sessionId;
+    private options;
+    private hmrHash;
+    constructor(options?: HmrServerOptions);
+    /**
+     * Create a MessageChannel and return the port that should be sent to the iframe.
+     * The other port is kept by the server for communication.
+     */
+    createConnection(): {
+        clientPort: MessagePort;
+        client: HmrClient;
+    };
+    /**
+     * Connect an iframe to the HMR server.
+     * This posts a message to the iframe with the client port.
+     */
+    connectIframe(iframe: HTMLIFrameElement, origin?: string): HmrClient | null;
+    private handleClientMessage;
+    private handleClientEvent;
+    private subscribe;
+    private unsubscribe;
+    private removeClient;
+    /**
+     * Send a Turbopack update to all subscribed clients for a specific path.
+     */
+    sendUpdate(path: string, update: TurbopackUpdate): void;
+    /**
+     * Broadcast an HMR message to all connected clients.
+     */
+    broadcast(message: HMR_ACTION_TYPES): void;
+    /**
+     * Send building notification to all clients.
+     */
+    sendBuilding(): void;
+    /**
+     * Send built notification to all clients.
+     */
+    sendBuilt(errors?: readonly unknown[], warnings?: readonly unknown[]): void;
+    /**
+     * Send reload request to all clients.
+     */
+    sendReload(reason: string): void;
+    /**
+     * Get all currently subscribed paths.
+     */
+    getSubscribedPaths(): string[];
+    /**
+     * Get number of connected clients.
+     */
+    get clientCount(): number;
+    /**
+     * Close all client connections.
+     */
+    close(): void;
+}

package/esm/hmr/HmrServer.js

@@ -0,0 +1,223 @@
+/**
+ * HmrServer - Simulates a WebSocket server using MessagePort for HMR communication.
+ *
+ * This class manages HMR connections with preview iframes, forwarding Turbopack
+ * HMR events from the main project to the preview iframe's HMR client.
+ *
+ * Architecture:
+ * - Main Thread (Project) -> HmrServer -> MessagePort -> Preview Iframe (HMR Client)
+ */
+import { HMR_ACTIONS_SENT_TO_BROWSER } from "@utoo/pack-shared";
+let clientIdCounter = 0;
+/**
+ * HmrServer manages HMR connections with preview iframes.
+ */
+export class HmrServer {
+    constructor(options = {}) {
+        var _a;
+        this.clients = new Set();
+        this.subscriptions = new Map();
+        this.hmrHash = 0;
+        this.options = options;
+        this.sessionId =
+            (_a = options.sessionId) !== null && _a !== void 0 ? _a : Math.floor(Number.MAX_SAFE_INTEGER * Math.random());
+    }
+    /**
+     * Create a MessageChannel and return the port that should be sent to the iframe.
+     * The other port is kept by the server for communication.
+     */
+    createConnection() {
+        const { port1, port2 } = new MessageChannel();
+        const clientId = `hmr-client-${++clientIdCounter}`;
+        const client = {
+            id: clientId,
+            port: port1,
+            send: (message) => {
+                port1.postMessage(JSON.stringify(message));
+            },
+            close: () => {
+                this.removeClient(client);
+                port1.close();
+            },
+        };
+        port1.onmessage = (event) => {
+            this.handleClientMessage(client, event.data);
+        };
+        port1.onmessageerror = () => {
+            this.removeClient(client);
+        };
+        this.clients.add(client);
+        // Send connected message
+        client.send({
+            action: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED,
+            data: { sessionId: this.sessionId },
+        });
+        // Send initial sync
+        client.send({
+            action: HMR_ACTIONS_SENT_TO_BROWSER.SYNC,
+            hash: String(this.hmrHash),
+            errors: [],
+            warnings: [],
+        });
+        return { clientPort: port2, client };
+    }
+    /**
+     * Connect an iframe to the HMR server.
+     * This posts a message to the iframe with the client port.
+     */
+    connectIframe(iframe, origin = "*") {
+        if (!iframe.contentWindow) {
+            console.warn("[HmrServer] Cannot connect: iframe has no contentWindow");
+            return null;
+        }
+        const { clientPort, client } = this.createConnection();
+        // Send the port to the iframe
+        iframe.contentWindow.postMessage({ type: "hmr-connect", sessionId: this.sessionId }, origin, [clientPort]);
+        return client;
+    }
+    handleClientMessage(client, data) {
+        try {
+            const message = typeof data === "string" ? JSON.parse(data) : data;
+            if ("type" in message) {
+                switch (message.type) {
+                    case "turbopack-subscribe":
+                        this.subscribe(client, message.path);
+                        break;
+                    case "turbopack-unsubscribe":
+                        this.unsubscribe(client, message.path);
+                        break;
+                }
+            }
+            // Handle other client events (client-error, client-success, etc.)
+            if ("event" in message) {
+                this.handleClientEvent(client, message);
+            }
+        }
+        catch (e) {
+            console.error("[HmrServer] Failed to parse client message:", e);
+        }
+    }
+    handleClientEvent(_client, message) {
+        switch (message.event) {
+            case "client-error":
+            case "client-warning":
+            case "client-success":
+                // These are informational, can be logged or forwarded
+                break;
+            case "client-full-reload":
+                if (message.hadRuntimeError) {
+                    console.warn("[HmrServer] Fast Refresh had to perform a full reload due to a runtime error.");
+                }
+                break;
+        }
+    }
+    subscribe(client, path) {
+        var _a, _b;
+        let clients = this.subscriptions.get(path);
+        if (!clients) {
+            clients = new Set();
+            this.subscriptions.set(path, clients);
+        }
+        clients.add(client);
+        (_b = (_a = this.options).onSubscribe) === null || _b === void 0 ? void 0 : _b.call(_a, path, client);
+    }
+    unsubscribe(client, path) {
+        var _a, _b;
+        const clients = this.subscriptions.get(path);
+        if (clients) {
+            clients.delete(client);
+            if (clients.size === 0) {
+                this.subscriptions.delete(path);
+            }
+        }
+        (_b = (_a = this.options).onUnsubscribe) === null || _b === void 0 ? void 0 : _b.call(_a, path, client);
+    }
+    removeClient(client) {
+        var _a, _b;
+        this.clients.delete(client);
+        // Remove from all subscriptions
+        for (const [path, clients] of this.subscriptions) {
+            if (clients.has(client)) {
+                clients.delete(client);
+                (_b = (_a = this.options).onUnsubscribe) === null || _b === void 0 ? void 0 : _b.call(_a, path, client);
+            }
+            if (clients.size === 0) {
+                this.subscriptions.delete(path);
+            }
+        }
+    }
+    /**
+     * Send a Turbopack update to all subscribed clients for a specific path.
+     */
+    sendUpdate(path, update) {
+        const clients = this.subscriptions.get(path);
+        if (!clients)
+            return;
+        const message = {
+            action: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_MESSAGE,
+            data: update,
+        };
+        for (const client of clients) {
+            client.send(message);
+        }
+    }
+    /**
+     * Broadcast an HMR message to all connected clients.
+     */
+    broadcast(message) {
+        for (const client of this.clients) {
+            client.send(message);
+        }
+    }
+    /**
+     * Send building notification to all clients.
+     */
+    sendBuilding() {
+        this.broadcast({
+            action: HMR_ACTIONS_SENT_TO_BROWSER.BUILDING,
+        });
+    }
+    /**
+     * Send built notification to all clients.
+     */
+    sendBuilt(errors = [], warnings = []) {
+        this.hmrHash++;
+        this.broadcast({
+            action: HMR_ACTIONS_SENT_TO_BROWSER.BUILT,
+            hash: String(this.hmrHash),
+            errors: errors,
+            warnings: warnings,
+        });
+    }
+    /**
+     * Send reload request to all clients.
+     */
+    sendReload(reason) {
+        this.broadcast({
+            action: HMR_ACTIONS_SENT_TO_BROWSER.RELOAD,
+            data: reason,
+        });
+    }
+    /**
+     * Get all currently subscribed paths.
+     */
+    getSubscribedPaths() {
+        return Array.from(this.subscriptions.keys());
+    }
+    /**
+     * Get number of connected clients.
+     */
+    get clientCount() {
+        return this.clients.size;
+    }
+    /**
+     * Close all client connections.
+     */
+    close() {
+        for (const client of this.clients) {
+            client.close();
+        }
+        this.clients.clear();
+        this.subscriptions.clear();
+    }
+}

package/esm/hmr/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HMR (Hot Module Replacement) module for browser-based utoopack.
+ *
+ * This module provides HMR support for preview iframes using MessagePort
+ * instead of WebSocket for communication.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * import { Project } from "@utoo/web";
+ *
+ * const project = new Project({ ... });
+ *
+ * // Start dev mode (creates HmrServer internally)
+ * project.dev((result) => {
+ *   console.log("Build complete", result);
+ * });
+ *
+ * // Connect iframe to receive HMR updates
+ * const client = project.connectHmrIframe(iframeElement);
+ * ```
+ *
+ * The HMR client runtime is in crates/pack-core/js/src/hmr/
+ * and is injected into the preview iframe by the build system.
+ */
+export { type BaseUpdate, type BuildingAction, type BuiltAction, type CompilationError, type EcmascriptMergedUpdate, type HMR_ACTION_TYPES, HMR_ACTIONS_SENT_TO_BROWSER, type HmrActionType, type HmrClientMessage, type HmrIssue, type HmrIssueSource, type IssuesUpdate, type NotFoundUpdate, type PartialUpdate, type ReloadAction, type ResourceIdentifier, type RestartUpdate, type SyncAction, type TurbopackConnectedAction, type TurbopackMessageAction, type TurbopackSubscribeMessage, type TurbopackUnsubscribeMessage, type TurbopackUpdate, type UpdateEndMessage, type UpdateInfo, type UpdateMessage, type UpdateStartMessage, } from "@utoo/pack-shared";
+export { type HmrClient, HmrServer, type HmrServerOptions } from "./HmrServer";

package/esm/hmr/index.js

@@ -0,0 +1,27 @@
+/**
+ * HMR (Hot Module Replacement) module for browser-based utoopack.
+ *
+ * This module provides HMR support for preview iframes using MessagePort
+ * instead of WebSocket for communication.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * import { Project } from "@utoo/web";
+ *
+ * const project = new Project({ ... });
+ *
+ * // Start dev mode (creates HmrServer internally)
+ * project.dev((result) => {
+ *   console.log("Build complete", result);
+ * });
+ *
+ * // Connect iframe to receive HMR updates
+ * const client = project.connectHmrIframe(iframeElement);
+ * ```
+ *
+ * The HMR client runtime is in crates/pack-core/js/src/hmr/
+ * and is injected into the preview iframe by the build system.
+ */
+export { HMR_ACTIONS_SENT_TO_BROWSER, } from "@utoo/pack-shared";
+export { HmrServer } from "./HmrServer";

package/esm/index.d.ts

@@ -1,3 +1,4 @@
 export { compatOptionsFromWebpack, type WebpackConfig, } from "@utoo/pack-shared";
+export * from "./hmr";
 export { Project } from "./project/Project";
 export * from "./types";

package/esm/index.js

@@ -1,3 +1,4 @@
 export { compatOptionsFromWebpack, } from "@utoo/pack-shared";
+export * from "./hmr";
 export { Project } from "./project/Project";
 export * from "./types";