@remix-run/node-hmr 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+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

@@ -1,3 +1,307 @@
-# Placeholder Package
+# node-hmr
 
-This package is a placeholder published at 0.0.0 to reserve the package name and configure CI publish permissions.
+Run Node.js applications with Hot Module Reloading.
+
+## Features
+
+- **HMR Runtime**: Provides an `import.meta.hot` API for modules that can handle hot updates
+- **Module Hook Friendly**: Use Node's module customization hooks API to automatically insert `import.meta.hot` usage
+- **Restart Fallback**: Restarts the child Node process when updates aren't accepted
+- **Fetch Proxy Support**: Wrap fetch handlers so requests are delayed/retried during server updates/restarts
+- **Browser HMR Integration**: Optionally hosts browser HMR coordination that survives child restarts
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+Create a development script that starts your app server with HMR enabled, along with any additional Node args, such as the `--import` flag to provide [Node module customization hooks](https://nodejs.org/api/module.html#customization-hooks) for [JSX syntax support](https://github.com/remix-run/remix/tree/main/packages/node-tsx) and [Remix component HMR](https://github.com/remix-run/remix/tree/main/packages/ui-hmr):
+
+```ts
+// hmr.ts
+import { run } from 'remix/node-hmr'
+
+run('./server.ts', {
+  nodeArgs: ['--import', 'remix/node-tsx', '--import', 'remix/ui-hmr/node'],
+  watch: {
+    ignore: ['**/node_modules/**'],
+  },
+})
+```
+
+Then run the script with Node:
+
+```json
+{
+  "scripts": {
+    "hmr": "NODE_ENV=development node hmr.ts"
+  }
+}
+```
+
+## Fetch Proxy Support
+
+During development, server updates can briefly leave your app unable to handle requests. In a server-only context, requests may be rejected while the child server is restarting. In a browser context, the browser may refresh or revalidate at the same time as a server restart, which can result in failed requests or a broken page.
+
+A stable proxy server can avoid this by continuing to listen on the public port while `node-hmr` updates the child server behind it. `createHmrReadyFetch()` works with any fetch handler, so you can compose it with `createFetchProxy()` from [`remix/fetch-proxy`](https://github.com/remix-run/remix/tree/main/packages/fetch-proxy) to forward requests to the child server while delaying or retrying requests during updates.
+
+```ts
+// hmr.ts
+import * as http from 'node:http'
+
+import { createFetchProxy } from 'remix/fetch-proxy'
+import { run, createHmrReadyFetch } from 'remix/node-hmr'
+import { createRequestListener } from 'remix/node-fetch-server'
+
+const hmrProxyPort = 44100
+const appPort = 44101
+
+const hmrRunner = run('./server.ts', {
+  env: {
+    ...process.env,
+    PORT: String(appPort),
+  },
+  nodeArgs: ['--import', 'remix/node-tsx'],
+})
+
+const proxyFetch = createFetchProxy(`http://127.0.0.1:${appPort}`, {
+  xForwardedHeaders: true,
+})
+
+const server = http.createServer(createRequestListener(createHmrReadyFetch(hmrRunner, proxyFetch)))
+
+server.listen(hmrProxyPort)
+```
+
+By default, `createHmrReadyFetch()` retries `GET` and `HEAD` requests when the wrapped fetch handler throws or returns a `502`, `503`, or `504` response, but only if the server updated or restarted while the request was in flight. You can customize this policy with `shouldRetry`:
+
+```ts
+let fetchWhenReady = createHmrReadyFetch(hmrRunner, proxyFetch, {
+  shouldRetry({ request, response }) {
+    if (request.method !== 'GET' && request.method !== 'HEAD') return false
+
+    return response === undefined || [502, 503, 504].includes(response.status)
+  },
+})
+```
+
+## Browser HMR Integration
+
+`node-hmr` can coordinate browser-facing HMR alongside server HMR. The parent process hosts the browser event stream, tracks files reported by asset servers in the child process, sends matching file events back to the child runtime, and emits the resulting browser updates to connected clients.
+
+This is co-ordinated through the use of a browser HMR channel which can be created within the app server when running in `node-hmr` via the `remix/node-hmr/runtime` import:
+
+```ts
+import { createBrowserHmrChannel } from 'remix/node-hmr/runtime'
+
+let browserHmrChannel = await createBrowserHmrChannel()
+```
+
+The `remix/node-hmr/runtime` API is only available inside a child process supervised by `node-hmr`. Importing it outside `node-hmr` throws. Supervised child processes automatically receive the `REMIX_NODE_HMR` environment variable which you can check before dynamically importing the runtime API:
+
+```ts
+if (process.env.REMIX_NODE_HMR) {
+  let { createBrowserHmrChannel } = await import('remix/node-hmr/runtime')
+  let browserHmrChannel = await createBrowserHmrChannel()
+}
+```
+
+A browser HMR channel is scoped to the current child process. It gives browser HMR tooling an EventSource URL, a way to report the files it wants watched, and a way to respond to file changes with browser HMR events.
+
+Browser asset servers can use this API to co-ordinate browser HMR with the server, for example, [`remix/assets`](https://github.com/remix-run/remix/tree/main/packages/assets) via its `hmr` option to `createAssetServer`:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let isDevelopment = process.env.NODE_ENV === 'development'
+
+let assetServer = createAssetServer({
+  basePath: '/assets',
+  fileMap: { '/app/*path': 'app/*path' },
+  allowFiles: ['app/routes.ts', 'app/**/public/**'],
+  denyFiles: ['app/**/*.test.*'],
+  hmr:
+    isDevelopment && process.env.REMIX_NODE_HMR
+      ? async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel()
+      : undefined,
+  watch: isDevelopment,
+})
+```
+
+When `node-hmr` hot updates or restarts server code in a way that should refresh server-rendered UI, it sends a `server:update` event to connected clients.
+
+Call `emitServerReady()` when your app server is ready to receive requests. This lets the parent process delay browser `server:update` events until a restarted app server has finished listening:
+
+```ts
+server.listen(port, () => {
+  if (process.env.REMIX_NODE_HMR) {
+    import('remix/node-hmr/runtime').then((nodeHmr) => nodeHmr.emitServerReady())
+  }
+})
+```
+
+## File Watching
+
+The file system is watched automatically so server source changes can hot update or restart the child process.
+
+You can optionally provide an array of glob patterns to the `watch.ignore` option.
+
+```ts
+import { run } from 'remix/node-hmr'
+
+run('./server.ts', {
+  nodeArgs: ['--import', 'remix/node-tsx', '--import', 'remix/ui-hmr/node'],
+  watch: {
+    ignore: ['**/node_modules/**'],
+  },
+})
+```
+
+You can also configure polling behavior. Polling defaults to `true` on Windows and `false` elsewhere:
+
+```ts
+import { run } from 'remix/node-hmr'
+
+run('./server.ts', {
+  nodeArgs: ['--import', 'remix/node-tsx', '--import', 'remix/ui-hmr/node'],
+  watch: {
+    poll: true,
+    pollInterval: 100,
+  },
+})
+```
+
+## `import.meta.hot`
+
+The `import.meta.hot` API provided by `node-hmr` is a small runtime contract for modules that can handle updates without restarting the process. It is primarily intended for transforms like [remix/ui-hmr](https://github.com/remix-run/remix/tree/main/packages/ui-hmr), but it can also be used directly.
+
+To type `import.meta.hot`, add the HMR types to your TypeScript config:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["remix/node-hmr/types"]
+  }
+}
+```
+
+HMR accept calls are statically analyzed. Write them directly as `import.meta.hot.accept(...)`. Dependency accepts must use string literals or arrays of string literals; do not alias `import.meta.hot` or pass dynamically constructed dependency lists.
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.accept()
+}
+```
+
+For consistency with browser HMR environments, `node-hmr` also implements `import.meta.hot.on(...)`, but no events are fired in server modules.
+
+### Accepting updates
+
+Calling `accept()` makes the current module an HMR boundary. When the module changes, `node-hmr` evaluates the updated module and calls your callback with its exports.
+
+```ts
+export let value = 1
+
+if (import.meta.hot) {
+  import.meta.hot.accept((module) => {
+    if (typeof module.value !== 'number') {
+      import.meta.hot?.invalidate('Updated module no longer exports value')
+      return
+    }
+
+    value = module.value
+  })
+}
+```
+
+You can also accept updates from direct dependencies.
+
+```ts
+import { value } from './value.ts'
+
+let currentValue = value
+
+export function readValue() {
+  return currentValue
+}
+
+if (import.meta.hot) {
+  import.meta.hot.accept('./value.ts', (module) => {
+    if (typeof module.value !== 'number') {
+      import.meta.hot?.invalidate('Updated dependency no longer exports value')
+      return
+    }
+
+    currentValue = module.value
+  })
+}
+```
+
+Multiple dependencies can be accepted at once. The callback receives an array where only the changed dependency is defined.
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.accept(['./one.ts', './two.ts'], ([oneModule, twoModule]) => {
+    // oneModule is defined when ./one.ts changed.
+    // twoModule is defined when ./two.ts changed.
+  })
+}
+```
+
+### Cleaning up
+
+Register cleanup that should run before the module is replaced or disposed.
+
+```ts
+let interval = setInterval(refreshCache, 30_000)
+
+if (import.meta.hot) {
+  import.meta.hot.dispose(() => {
+    clearInterval(interval)
+  })
+}
+```
+
+The `data` object is preserved across updates for the same module. Use it for small pieces of state.
+
+```ts
+let count = Number(import.meta.hot?.data.count ?? 0)
+
+export function increment() {
+  count++
+}
+
+if (import.meta.hot) {
+  import.meta.hot.dispose((data) => {
+    data.count = count
+  })
+}
+```
+
+### Invalidating updates
+
+Call `invalidate()` inside an accept callback when the update cannot be applied safely. `node-hmr` falls back to a process restart.
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.accept((module) => {
+    if (typeof module.value !== 'number') {
+      import.meta.hot?.invalidate('Updated module no longer exports value')
+      return
+    }
+  })
+}
+```
+
+## Related Packages
+
+- [`assets`](https://github.com/remix-run/remix/tree/main/packages/assets) - Consumes browser HMR channels for coordinating server and browser HMR updates
+- [`fetch-proxy`](https://github.com/remix-run/remix/tree/main/packages/fetch-proxy) - Creates fetch handlers for forwarding requests to another server
+- [`ui-hmr`](https://github.com/remix-run/remix/tree/main/packages/ui-hmr) - Provides code transforms and runtime for HMR for Remix UI components
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Options for running a Node.js entry module with HMR supervision.
+ */
+export interface RunOptions {
+    /**
+     * Configures the parent-owned EventSource server used to coordinate browser HMR, or disables it
+     * with `false`. Enabled with default options when omitted or set to `true`.
+     */
+    browserHmrChannel?: boolean | BrowserHmrChannelOptions;
+    /** Working directory used to resolve the entry path and relative watch options. (`process.cwd()`) */
+    cwd?: string;
+    /** Arguments passed to the entry module after the entry path. */
+    entryArgs?: readonly string[];
+    /** Complete environment for the child process. (`process.env`) */
+    env?: NodeJS.ProcessEnv;
+    /** Node.js arguments passed before the entry path. */
+    nodeArgs?: readonly string[];
+    /** File watching options for the supervised process. */
+    watch?: NodeHmrWatchOptions;
+}
+/**
+ * Browser HMR event stream options hosted by the parent process.
+ */
+export interface BrowserHmrChannelOptions {
+    /** Hostname for the browser HMR event server. (`'127.0.0.1'`) */
+    host?: string;
+    /** Port for the browser HMR event server. Uses an available ephemeral port when omitted. */
+    port?: number;
+    /** URL pathname for the browser HMR event stream. (`'/hmr'`) */
+    pathname?: string;
+}
+/**
+ * File watching options for a Node HMR runner.
+ */
+export interface NodeHmrWatchOptions {
+    /**
+     * Ignore matching glob patterns or file paths. Relative values are resolved
+     * from the runner's `cwd`.
+     */
+    ignore?: readonly string[];
+    /**
+     * Use polling instead of native filesystem events. Defaults to `true` on
+     * Windows and `false` elsewhere.
+     */
+    poll?: boolean;
+    /**
+     * Polling interval in milliseconds when `poll` is enabled. Defaults to `100`.
+     */
+    pollInterval?: number;
+}
+/**
+ * Handle returned by {@link run} for controlling the supervised process.
+ */
+export interface NodeHmrRunner {
+    /**
+     * Stops the runner and waits for the child process to exit.
+     *
+     * @returns A promise that resolves once the runner has stopped.
+     */
+    close(): Promise<void>;
+    /**
+     * Current server generation, incremented after every accepted hot update or process restart.
+     */
+    readonly generation: number;
+    /**
+     * Waits until the latest update or restart has settled and the current child process is ready.
+     *
+     * If the app uses `emitServerReady()`, restart readiness also waits for that signal.
+     *
+     * @returns A promise that resolves when the latest requested generation is ready.
+     */
+    ready(): Promise<void>;
+}
+type HmrReadyFetchRetryContext = {
+    /** Child process lifecycle generation that handled the fetch attempt. */
+    generation: number;
+    /** Request passed to the wrapped fetch handler. */
+    request: Request;
+} & ({
+    /** Error thrown by the wrapped fetch handler. */
+    error: unknown;
+    /** Response is absent when the wrapped fetch handler throws. */
+    response?: never;
+} | {
+    /** Error is absent when the wrapped fetch handler returns a response. */
+    error?: never;
+    /** Response returned by the wrapped fetch handler. */
+    response: Response;
+});
+/**
+ * Options for {@link createHmrReadyFetch}.
+ */
+export interface HmrReadyFetchOptions {
+    /**
+     * Determines whether a response or thrown error should be retried if the
+     * runner moves to a new generation while the request is in flight. Defaults
+     * to retrying `GET` and `HEAD` requests when the fetch throws or returns
+     * `502`, `503`, or `504`.
+     */
+    shouldRetry?: (context: HmrReadyFetchRetryContext) => boolean | Promise<boolean>;
+}
+/**
+ * Wraps a fetch handler so requests wait for the current HMR generation to be ready.
+ *
+ * If the wrapped fetch handler returns a retryable response or throws a retryable error, the
+ * request is attempted again only when the runner moved to a new generation while the request was
+ * in flight.
+ *
+ * @param runner HMR runner that controls server readiness.
+ * @param fetch Fetch handler to call once the runner is ready.
+ * @param options Retry behavior for responses and thrown errors.
+ * @returns A fetch handler that waits for HMR readiness before forwarding requests.
+ */
+export declare function createHmrReadyFetch(runner: NodeHmrRunner, fetch: (request: Request) => Response | Promise<Response>, options?: HmrReadyFetchOptions): (request: Request) => Promise<Response>;
+/**
+ * Starts a Node.js entry module in a supervised child process and watches its loaded module graph.
+ *
+ * Accepted module changes are applied in place; unaccepted changes restart the child. The returned
+ * handle exposes readiness across both paths and closes the watcher, child process, and browser HMR
+ * event server when stopped.
+ *
+ * @param entry Entry module path, resolved from `options.cwd`.
+ * @param options Runner options.
+ * @returns A runner handle for the supervised process.
+ */
+export declare function run(entry: string, options?: RunOptions): NodeHmrRunner;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,wBAAwB,CAAA;IACtD,qGAAqG;IACrG,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,iEAAiE;IACjE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,wDAAwD;IACxD,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,KAAK,yBAAyB,GAAG;IAC/B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAA;CACjB,GAAG,CACA;IACE,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAA;IACd,gEAAgE;IAChE,QAAQ,CAAC,EAAE,KAAK,CAAA;CACjB,GACD;IACE,yEAAyE;IACzE,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,sDAAsD;IACtD,QAAQ,EAAE,QAAQ,CAAA;CACnB,CACJ,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACjF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,EACzD,OAAO,GAAE,oBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA8BzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,aAAa,CA8B1E"}

package/dist/index.js

@@ -0,0 +1,107 @@
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { createHmrSupervisor } from './lib/runner.js';
+/**
+ * Wraps a fetch handler so requests wait for the current HMR generation to be ready.
+ *
+ * If the wrapped fetch handler returns a retryable response or throws a retryable error, the
+ * request is attempted again only when the runner moved to a new generation while the request was
+ * in flight.
+ *
+ * @param runner HMR runner that controls server readiness.
+ * @param fetch Fetch handler to call once the runner is ready.
+ * @param options Retry behavior for responses and thrown errors.
+ * @returns A fetch handler that waits for HMR readiness before forwarding requests.
+ */
+export function createHmrReadyFetch(runner, fetch, options = {}) {
+    let shouldRetry = options.shouldRetry ?? shouldRetrySafeUnavailableRequest;
+    return async (request) => {
+        while (true) {
+            await runner.ready();
+            let generation = runner.generation;
+            try {
+                let response = await fetch(request);
+                if (!(await shouldRetry({ generation, request, response }))) {
+                    return response;
+                }
+                await runner.ready();
+                if (runner.generation !== generation)
+                    continue;
+                return response;
+            }
+            catch (error) {
+                await runner.ready();
+                if (runner.generation !== generation &&
+                    (await shouldRetry({ error, generation, request }))) {
+                    continue;
+                }
+                throw error;
+            }
+        }
+    };
+}
+/**
+ * Starts a Node.js entry module in a supervised child process and watches its loaded module graph.
+ *
+ * Accepted module changes are applied in place; unaccepted changes restart the child. The returned
+ * handle exposes readiness across both paths and closes the watcher, child process, and browser HMR
+ * event server when stopped.
+ *
+ * @param entry Entry module path, resolved from `options.cwd`.
+ * @param options Runner options.
+ * @returns A runner handle for the supervised process.
+ */
+export function run(entry, options = {}) {
+    let supervisor = createHmrSupervisor({
+        browserHmrChannel: normalizeBrowserHmrChannelOptions(options.browserHmrChannel),
+        cwd: options.cwd ?? process.cwd(),
+        entry,
+        entryArgs: [...(options.entryArgs ?? [])],
+        env: options.env ?? process.env,
+        nodeArgs: [...(options.nodeArgs ?? [])],
+        registerPath: resolveRegisterPath(),
+        watch: options.watch,
+    });
+    let closed = supervisor.start();
+    closed.catch((error) => {
+        console.error(error);
+    });
+    return {
+        close() {
+            return supervisor.stop();
+        },
+        get generation() {
+            return supervisor.generation;
+        },
+        ready() {
+            return supervisor.ready();
+        },
+    };
+}
+function shouldRetrySafeUnavailableRequest({ request, response, }) {
+    if (request.method !== 'GET' && request.method !== 'HEAD')
+        return false;
+    return (response === undefined ||
+        response.status === 502 ||
+        response.status === 503 ||
+        response.status === 504);
+}
+function normalizeBrowserHmrChannelOptions(options) {
+    if (options === false)
+        return null;
+    if (options === undefined || options === true)
+        return {};
+    if (options.port !== undefined) {
+        assertValidPort(options.port);
+    }
+    return options;
+}
+function resolveRegisterPath() {
+    let extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+    return fileURLToPath(new URL(`./register.${extension}`, import.meta.url));
+}
+function assertValidPort(port) {
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new TypeError(`Invalid browser HMR channel port: ${port}`);
+    }
+}

package/dist/lib/browser-events.d.ts

@@ -0,0 +1,99 @@
+export declare const defaultBrowserHmrPathname = "/hmr";
+/**
+ * Event payload sent to browser HMR clients.
+ */
+export interface HmrEventPayload {
+    /** Event type string consumed by browser HMR clients. */
+    type: string;
+    [key: string]: unknown;
+}
+/** JavaScript or CSS module update sent to a browser HMR client. */
+export type HmrBrowserUpdate = {
+    /** Importing module whose dependency-accept handler accepts this update. */
+    acceptedPath?: string;
+    /** Public URL of the changed JavaScript module. */
+    path: string;
+    /** Identifies a JavaScript module update. */
+    type: 'js';
+} | {
+    /** Public URL of the changed stylesheet. */
+    path: string;
+    /** Identifies a stylesheet update. */
+    type: 'css';
+};
+/**
+ * Browser HMR event emitted to connected clients.
+ */
+export type BrowserHmrEvent = {
+    /** Absolute source file paths that triggered this update. */
+    files?: string[];
+    /** Update timestamp used to bust module and stylesheet caches. */
+    timestamp: number;
+    /** Browser update event. */
+    type: 'update';
+    /** JavaScript and CSS updates for the browser to apply. */
+    updates: HmrBrowserUpdate[];
+} | {
+    /** Absolute source file paths that could not be handled in place. */
+    files?: string[];
+    /** Browser reload event. */
+    type: 'reload';
+};
+/**
+ * File watcher event reported to a browser HMR channel.
+ */
+export type BrowserHmrFileEvent = {
+    /** Filesystem operation observed by the parent watcher. */
+    event: 'add' | 'change' | 'unlink';
+    /** Absolute path of the source file that changed. */
+    filePath: string;
+};
+/**
+ * Handles file events and returns browser HMR events to emit.
+ *
+ * @param events File additions, changes, and removals reported together by the parent watcher.
+ * @returns Browser events to publish in their returned order.
+ */
+export type BrowserHmrFileEventHandler = (events: readonly BrowserHmrFileEvent[]) => Promise<readonly BrowserHmrEvent[]>;
+/**
+ * Watched file delta for a browser HMR channel.
+ */
+export interface BrowserHmrWatchedFileDelta {
+    /** Absolute source file paths newly required by this channel. */
+    add: readonly string[];
+    /** Absolute source file paths no longer required by this channel. */
+    remove: readonly string[];
+}
+/**
+ * Child-process bridge between browser asset tooling and the parent `node-hmr` runtime.
+ *
+ * The channel contributes files to the parent's shared watcher and converts matching file changes
+ * into browser update or reload events. Close it when its owning asset server shuts down.
+ */
+export interface BrowserHmrChannel {
+    /** Absolute URL of the parent-owned EventSource endpoint for browser HMR clients. */
+    readonly url: string;
+    /** Closes this channel, unregisters its handlers, and removes its files from the parent watcher. */
+    close(): void;
+    /**
+     * Registers a handler that converts matching watcher events into events for browser clients.
+     *
+     * Multiple handlers may be registered; their returned browser events are concatenated. Calling
+     * the returned cleanup function stops invoking this handler without closing the channel.
+     *
+     * @param handler Callback that maps a batch of file changes to browser HMR events.
+     * @returns A cleanup function that unregisters only this handler.
+     */
+    onFileEvents(handler: BrowserHmrFileEventHandler): () => void;
+    /**
+     * Adds and removes absolute file paths from the parent process's watcher for this channel.
+     *
+     * Paths remain watched until removed by a later delta or until the channel is closed. Repeated
+     * additions and removals are idempotent.
+     *
+     * @param delta Files to add and remove from the watcher.
+     */
+    updateWatchedFiles(delta: BrowserHmrWatchedFileDelta): void;
+}
+export declare function sendHmrEventPayload(payload: HmrEventPayload): void;
+//# sourceMappingURL=browser-events.d.ts.map

package/dist/lib/browser-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-events.d.ts","sourceRoot":"","sources":["../../src/lib/browser-events.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,yBAAyB,SAAS,CAAA;AAE/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAA;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,oEAAoE;AACpE,MAAM,MAAM,gBAAgB,GACxB;IACE,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,IAAI,EAAE,IAAI,CAAA;CACX,GACD;IACE,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,sCAAsC;IACtC,IAAI,EAAE,KAAK,CAAA;CACZ,CAAA;AAEL;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB;IACE,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAA;IACjB,4BAA4B;IAC5B,IAAI,EAAE,QAAQ,CAAA;IACd,2DAA2D;IAC3D,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAC5B,GACD;IACE,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,4BAA4B;IAC5B,IAAI,EAAE,QAAQ,CAAA;CACf,CAAA;AAEL;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,2DAA2D;IAC3D,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;IAClC,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,MAAM,EAAE,SAAS,mBAAmB,EAAE,KACnC,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAAA;AAExC;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,GAAG,EAAE,SAAS,MAAM,EAAE,CAAA;IACtB,qEAAqE;IACrE,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,oGAAoG;IACpG,KAAK,IAAI,IAAI,CAAA;IACb;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,0BAA0B,GAAG,MAAM,IAAI,CAAA;IAC7D;;;;;;;OAOG;IACH,kBAAkB,CAAC,KAAK,EAAE,0BAA0B,GAAG,IAAI,CAAA;CAC5D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAOlE"}

package/dist/lib/browser-events.js

@@ -0,0 +1,11 @@
+import process from 'node:process';
+import { hasNodeHmrParentProcess } from './process-state.js';
+export const defaultBrowserHmrPathname = '/hmr';
+export function sendHmrEventPayload(payload) {
+    if (!hasNodeHmrParentProcess())
+        return;
+    process.send?.({
+        payload,
+        type: 'node-hmr:child:browser-event-emitted',
+    });
+}