bippy 0.5.42 → 0.6.0

package/src/rdt-hook.ts

@@ -4,6 +4,7 @@
 // make sure you import this file first before anything else (particularly React)
 
 import type { ReactDevToolsGlobalHook, ReactRenderer } from "./types.js";
+import { toUnsubscribe, type Unsubscribe } from "./unsubscribe.js";
 
 export const version = process.env.VERSION;
 export const BIPPY_INSTRUMENTATION_STRING = `bippy-${version}`;
@@ -16,9 +17,9 @@ const NO_OP = () => {
   /**/
 };
 
-const checkDCE = (fn: unknown): void => {
+const checkDCE = (functionToCheck: unknown): void => {
   try {
-    const code = Function.prototype.toString.call(fn);
+    const code = Function.prototype.toString.call(functionToCheck);
     if (code.indexOf("^_^") > -1) {
       setTimeout(() => {
         throw new Error(
@@ -52,27 +53,67 @@ export const isReactRefresh = (
   return Boolean(injectFnStr?.includes("(injected)"));
 };
 
-const onActiveListeners = new Set<() => unknown>();
+export const _onActiveListeners = new Set<() => unknown>();
 
 export const _renderers = new Set<ReactRenderer>();
 
+const rendererInjectListeners = new Set<(renderer: ReactRenderer) => void>();
+// re-wrapping inject (e.g. after the hook is replaced) leaves the old
+// wrapper in the call chain, so notifications are deduped per renderer
+const notifiedRenderers = new WeakSet<ReactRenderer>();
+let notifyingInject: ReactDevToolsGlobalHook["inject"] | null = null;
+
+const ensureInjectNotifiesListeners = (rdtHook: ReactDevToolsGlobalHook): void => {
+  if (rdtHook.inject === notifyingInject) return;
+  const prevInject = rdtHook.inject;
+  const nextInject = (renderer: ReactRenderer) => {
+    const rendererId = prevInject.call(rdtHook, renderer);
+    if (!notifiedRenderers.has(renderer)) {
+      notifiedRenderers.add(renderer);
+      for (const listener of rendererInjectListeners) {
+        listener(renderer);
+      }
+    }
+    return rendererId;
+  };
+  rdtHook.inject = nextInject;
+  notifyingInject = nextInject;
+};
+
+/**
+ * Subscribes to future renderer injections into the DevTools hook. The
+ * single shared inject wrapper lets multiple consumers (override methods,
+ * react-refresh, user code) observe renderers without stacking patches
+ * whose restore order matters. Returns an unsubscribe function.
+ */
+export const onRendererInject = (listener: (renderer: ReactRenderer) => void): Unsubscribe => {
+  ensureInjectNotifiesListeners(getRDTHook());
+  rendererInjectListeners.add(listener);
+  return toUnsubscribe(() => {
+    rendererInjectListeners.delete(listener);
+  });
+};
+
 export const installRDTHook = (onActive?: () => unknown): ReactDevToolsGlobalHook => {
+  if (onActive) {
+    _onActiveListeners.add(onActive);
+  }
   const renderers = new Map<number, ReactRenderer>();
-  let i = 0;
+  let rendererIdCounter = 0;
   let rdtHook: ReactDevToolsGlobalHook = {
     _instrumentationIsActive: false,
     _instrumentationSource: BIPPY_INSTRUMENTATION_STRING,
     checkDCE,
     hasUnsupportedRendererAttached: false,
     inject(renderer) {
-      const nextID = ++i;
-      renderers.set(nextID, renderer);
+      const nextRendererId = ++rendererIdCounter;
+      renderers.set(nextRendererId, renderer);
       _renderers.add(renderer);
       if (!rdtHook._instrumentationIsActive) {
         rdtHook._instrumentationIsActive = true;
-        onActiveListeners.forEach((listener) => listener());
+        _onActiveListeners.forEach((listener) => listener());
       }
-      return nextID;
+      return nextRendererId;
     },
     on: NO_OP,
     onCommitFiberRoot: NO_OP,
@@ -132,7 +173,7 @@ export const installRDTHook = (onActive?: () => unknown): ReactDevToolsGlobalHoo
 
 export const patchRDTHook = (onActive?: () => unknown): void => {
   if (onActive) {
-    onActiveListeners.add(onActive);
+    _onActiveListeners.add(onActive);
   }
   try {
     const rdtHook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
@@ -151,7 +192,7 @@ export const patchRDTHook = (onActive?: () => unknown): void => {
       }
       if (rdtHook.renderers.size) {
         rdtHook._instrumentationIsActive = true;
-        onActiveListeners.forEach((listener) => listener());
+        _onActiveListeners.forEach((listener) => listener());
         return;
       }
       const prevInject = rdtHook.inject;
@@ -160,24 +201,24 @@ export const patchRDTHook = (onActive?: () => unknown): void => {
         isReactRefreshOverride = true;
         // but since the underlying implementation doens't care,
         // it's ok: https://github.com/facebook/react/blob/18eaf51bd51fed8dfed661d64c306759101d0bfd/packages/react-refresh/src/ReactFreshRuntime.js#L430
-        const nextID = rdtHook.inject({
+        const injectedRendererId = rdtHook.inject({
           scheduleRefresh() {},
         } as unknown as ReactRenderer);
-        if (nextID) {
+        if (injectedRendererId) {
           rdtHook._instrumentationIsActive = true;
         }
       }
       rdtHook.inject = (renderer) => {
-        const id = prevInject(renderer);
+        const rendererId = prevInject(renderer);
         _renderers.add(renderer);
         if (isRefresh) {
           // react refresh doesn't inject this properly
           // https://github.com/facebook/react/blob/18eaf51bd51fed8dfed661d64c306759101d0bfd/packages/react-refresh/src/ReactFreshRuntime.js#L430
-          rdtHook.renderers.set(id, renderer);
+          rdtHook.renderers.set(rendererId, renderer);
         }
         rdtHook._instrumentationIsActive = true;
-        onActiveListeners.forEach((listener) => listener());
-        return id;
+        _onActiveListeners.forEach((listener) => listener());
+        return rendererId;
       };
     }
     if (

package/src/react-refresh/constants.ts

@@ -0,0 +1,9 @@
+export const HMR_RECONNECT_DELAY_MS = 1000;
+
+export const PENDING_HOT_UPDATE_MAX_AGE_MS = 10_000;
+
+export const VITE_WS_TOKEN_REGEX = /wsToken = "([^"]+)"/;
+
+export const HMR_SOURCE_FILE_EXTENSION_REGEX = /\.(?:tsx|ts|jsx|js|mjs|cjs|css)$/;
+
+export const BUNDLER_LAYER_PREFIX_REGEX = /^(?:\.\/)?\/?\([a-z][a-z0-9-]*\)\//;

package/src/react-refresh/detect-hmr-transport.ts

@@ -0,0 +1,33 @@
+import { isClientEnvironment } from "../rdt-hook.js";
+
+import { createMetroHmrTransport } from "./metro-hmr-transport.js";
+import { createNextWebpackHmrTransport } from "./next-webpack-hmr-transport.js";
+import { HmrTransport, HmrUpdateHandler } from "./types.js";
+import { createViteHmrTransport } from "./vite-hmr-transport.js";
+
+/**
+ * Detects the dev server's HMR transport (Next.js webpack, then Metro for
+ * React Native, then Vite) and subscribes `onHmrUpdate` to hot updates.
+ * Resolves `null` on the server (SSR) and when no known transport is
+ * available (production builds, unsupported bundlers — Turbopack exposes
+ * `window.TURBOPACK_CHUNK_UPDATE_LISTENERS` but its update payload shape
+ * has not been validated, so it is not wired up yet).
+ *
+ * @example
+ * ```ts
+ * const transport = await detectHmrTransport((filePaths) => {
+ *   console.log("hot updated:", filePaths);
+ * });
+ * transport?.dispose();
+ * ```
+ */
+export const detectHmrTransport = async (
+  onHmrUpdate: HmrUpdateHandler,
+): Promise<HmrTransport | null> => {
+  if (!isClientEnvironment()) return null;
+  const webpackTransport = createNextWebpackHmrTransport(onHmrUpdate);
+  if (webpackTransport) return webpackTransport;
+  const metroTransport = createMetroHmrTransport(onHmrUpdate);
+  if (metroTransport) return metroTransport;
+  return createViteHmrTransport(onHmrUpdate);
+};

package/src/react-refresh/index.ts

@@ -0,0 +1,173 @@
+import { getType, traverseFiber } from "../core.js";
+import { getRDTHook, isClientEnvironment, onRendererInject } from "../rdt-hook.js";
+import type { Fiber, FiberRoot, ReactRenderer } from "../types.js";
+import { toUnsubscribe, type Unsubscribe } from "../unsubscribe.js";
+import { PENDING_HOT_UPDATE_MAX_AGE_MS } from "./constants.js";
+import { detectHmrTransport } from "./detect-hmr-transport.js";
+import { HmrTransport } from "./types.js";
+
+export interface ReactRefreshUpdate {
+  /**
+   * hot-updated source file paths reported by the bundler's HMR transport
+   * (auto-detected: Next.js webpack, Metro, Vite). Best-effort: empty when
+   * the bundler does not expose a transport (e.g. Turbopack) or when the
+   * transport message has not arrived yet (e.g. Metro delivers updates on
+   * an independent socket).
+   */
+  filePaths: string[];
+  root: FiberRoot;
+  /** new component types that were remounted, losing state */
+  staleComponents: unknown[];
+  /** mounted fibers whose component types were remounted */
+  staleFibers: Fiber[];
+  /** new component types that re-rendered preserving state */
+  updatedComponents: unknown[];
+  /** mounted fibers whose component types re-rendered preserving state */
+  updatedFibers: Fiber[];
+}
+
+export interface ReactRefreshHandler {
+  (update: ReactRefreshUpdate): void;
+}
+
+export interface ReactRefreshInstrumentationOptions {
+  onRefresh?: ReactRefreshHandler;
+}
+
+const collectFibersByComponentType = (root: FiberRoot, componentTypes: Set<unknown>): Fiber[] => {
+  if (componentTypes.size === 0 || !root.current) return [];
+  const matchedFibers: Fiber[] = [];
+  traverseFiber(root.current, (fiber) => {
+    // memo/forwardRef fibers carry the wrapper as fiber.type, while the
+    // refresh families can register either the wrapper or the inner type
+    if (componentTypes.has(fiber.type) || componentTypes.has(getType(fiber.type))) {
+      matchedFibers.push(fiber);
+    }
+  });
+  return matchedFibers;
+};
+
+const refreshHandlers = new Set<ReactRefreshHandler>();
+const refreshWrappedRenderers = new WeakSet<ReactRenderer>();
+
+let pendingFilePaths: string[] = [];
+let pendingFilePathsReceivedAtMs = 0;
+
+const bufferHotUpdateFilePaths = (filePaths: string[]): void => {
+  const nowMs = Date.now();
+  if (nowMs - pendingFilePathsReceivedAtMs > PENDING_HOT_UPDATE_MAX_AGE_MS) {
+    pendingFilePaths = [];
+  }
+  pendingFilePaths.push(...filePaths);
+  pendingFilePathsReceivedAtMs = nowMs;
+};
+
+const takeFreshFilePaths = (): string[] => {
+  if (Date.now() - pendingFilePathsReceivedAtMs > PENDING_HOT_UPDATE_MAX_AGE_MS) return [];
+  const freshFilePaths = [...pendingFilePaths];
+  // performReactRefresh calls scheduleRefresh synchronously once per
+  // mounted root, so clear the pending paths only after the whole
+  // refresh pass instead of on the first root
+  queueMicrotask(() => {
+    pendingFilePaths = [];
+  });
+  return freshFilePaths;
+};
+
+const wrapRendererScheduleRefresh = (renderer: ReactRenderer): void => {
+  if (refreshWrappedRenderers.has(renderer)) return;
+  const originalScheduleRefresh = renderer.scheduleRefresh;
+  if (typeof originalScheduleRefresh !== "function") return;
+  refreshWrappedRenderers.add(renderer);
+  renderer.scheduleRefresh = (root, update) => {
+    originalScheduleRefresh.call(renderer, root, update);
+    if (refreshHandlers.size === 0) return;
+    const staleComponents = Array.from(update.staleFamilies, (family) => family.current);
+    const updatedComponents = Array.from(update.updatedFamilies, (family) => family.current);
+    const refreshUpdate: ReactRefreshUpdate = {
+      filePaths: takeFreshFilePaths(),
+      root,
+      staleComponents,
+      staleFibers: collectFibersByComponentType(root, new Set(staleComponents)),
+      updatedComponents,
+      updatedFibers: collectFibersByComponentType(root, new Set(updatedComponents)),
+    };
+    for (const handler of refreshHandlers) {
+      handler(refreshUpdate);
+    }
+  };
+};
+
+let isRefreshWired = false;
+
+const ensureRefreshWired = (): void => {
+  if (isRefreshWired) return;
+  isRefreshWired = true;
+  const rdtHook = getRDTHook();
+  for (const renderer of rdtHook.renderers.values()) {
+    wrapRendererScheduleRefresh(renderer);
+  }
+  onRendererInject(wrapRendererScheduleRefresh);
+};
+
+let activeTransport: HmrTransport | null = null;
+
+// the bundler's HMR global may not exist yet when an early subscriber
+// arrives, so detection is retried whenever the first subscriber (re)appears
+const detectTransportForNewSubscriber = (): void => {
+  void detectHmrTransport(bufferHotUpdateFilePaths).then((detectedTransport) => {
+    if (!detectedTransport) return;
+    activeTransport?.dispose();
+    activeTransport = detectedTransport;
+  });
+};
+
+/**
+ * Subscribes to react-refresh (fast refresh) updates by wrapping
+ * `scheduleRefresh` on every renderer injected into the React DevTools
+ * global hook. The react-refresh runtime calls `scheduleRefresh` after each
+ * hot update, so this works with any bundler that uses react-refresh (Vite,
+ * Next.js webpack, Next.js Turbopack, Metro) without bundler-specific code.
+ * Returns an unsubscribe function (a no-op in non-client environments like
+ * SSR, so callers never need an environment check). The returned function
+ * is also a `Disposable`, so it composes with other bippy subscriptions
+ * through `using`.
+ *
+ * The bundler's HMR transport is auto-detected and each refresh update is
+ * augmented with the hot-updated source file paths it reported.
+ *
+ * The handler runs after React has re-rendered with the new component
+ * types, so the refreshed root's fiber tree already carries them;
+ * `updatedFibers`/`staleFibers` are the mounted fibers matching the
+ * hot-swapped component types.
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = instrumentReactRefresh({
+ *   onRefresh(update) {
+ *     for (const fiber of update.updatedFibers) {
+ *       console.log("hot updated:", getDisplayName(fiber.type));
+ *     }
+ *     console.log("changed files:", update.filePaths);
+ *   },
+ * });
+ * unsubscribe();
+ * ```
+ *
+ * Pair with `getSource(fiber)` from `bippy/source` to symbolicate the
+ * source locations of `updatedFibers` when needed.
+ */
+export const instrumentReactRefresh = (
+  options: ReactRefreshInstrumentationOptions,
+): Unsubscribe => {
+  const { onRefresh } = options;
+  if (!onRefresh || !isClientEnvironment()) return toUnsubscribe(() => {});
+  ensureRefreshWired();
+  if (refreshHandlers.size === 0) {
+    detectTransportForNewSubscriber();
+  }
+  refreshHandlers.add(onRefresh);
+  return toUnsubscribe(() => {
+    refreshHandlers.delete(onRefresh);
+  });
+};

package/src/react-refresh/metro-hmr-transport.ts

@@ -0,0 +1,188 @@
+import { HMR_RECONNECT_DELAY_MS } from "./constants.js";
+import { HmrTransport, HmrUpdateHandler } from "./types.js";
+
+declare global {
+  var __turboModuleProxy: ((moduleName: string) => unknown) | undefined;
+  var nativeModuleProxy: Record<string, unknown> | undefined;
+}
+
+const getScriptUrlFromSourceCodeModule = (sourceCodeModule: unknown): string | null => {
+  if (typeof sourceCodeModule !== "object" || sourceCodeModule === null) return null;
+  if (!("getConstants" in sourceCodeModule)) return null;
+  const getConstants = sourceCodeModule.getConstants;
+  if (typeof getConstants !== "function") return null;
+  let constants: unknown;
+  try {
+    constants = getConstants.call(sourceCodeModule);
+  } catch {
+    return null;
+  }
+  if (typeof constants !== "object" || constants === null) return null;
+  if (!("scriptURL" in constants)) return null;
+  const scriptUrl = constants.scriptURL;
+  return typeof scriptUrl === "string" ? scriptUrl : null;
+};
+
+/**
+ * Resolves the URL the running React Native bundle was loaded from, using
+ * the same `SourceCode` native module React Native's own dev tooling reads
+ * (via the TurboModule proxy globals, so react-native is not imported).
+ * Returns `null` outside a Metro-served React Native runtime.
+ *
+ * @example
+ * ```ts
+ * getMetroBundleUrl();
+ * // "http://localhost:8081/index.bundle?platform=ios&dev=true"
+ * ```
+ */
+export const getMetroBundleUrl = (): string | null => {
+  if (typeof globalThis.__turboModuleProxy === "function") {
+    let sourceCodeModule: unknown;
+    try {
+      sourceCodeModule = globalThis.__turboModuleProxy("SourceCode");
+    } catch {
+      sourceCodeModule = null;
+    }
+    const scriptUrl = getScriptUrlFromSourceCodeModule(sourceCodeModule);
+    if (scriptUrl) return scriptUrl;
+  }
+  const legacySourceCodeModule = globalThis.nativeModuleProxy?.SourceCode;
+  return getScriptUrlFromSourceCodeModule(legacySourceCodeModule);
+};
+
+// HACK: module sourceURLs may be JSC-safe URLs where "//&" stands in for
+// "?" (iOS 16.4 stack traces strip query strings), so the query separator
+// must be normalized before URL parsing.
+const normalizeJscSafeUrl = (jscSafeUrl: string): string => jscSafeUrl.replace("//&", "?");
+
+const getSourcePathFromSourceUrl = (sourceUrl: string): string | null => {
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(normalizeJscSafeUrl(sourceUrl));
+  } catch {
+    return null;
+  }
+  let sourcePath = decodeURIComponent(parsedUrl.pathname);
+  if (sourcePath.startsWith("/")) sourcePath = sourcePath.slice(1);
+  // Metro rewrites each module's real extension to ".bundle" when building
+  // hot-update sourceURLs, so the original extension is unrecoverable.
+  if (sourcePath.endsWith(".bundle")) sourcePath = sourcePath.slice(0, -".bundle".length);
+  return sourcePath.length > 0 ? sourcePath : null;
+};
+
+const collectModuleSourcePaths = (hmrModules: unknown, filePaths: string[]) => {
+  if (!Array.isArray(hmrModules)) return;
+  for (const hmrModule of hmrModules) {
+    if (typeof hmrModule !== "object" || hmrModule === null) continue;
+    if (!("sourceURL" in hmrModule) || typeof hmrModule.sourceURL !== "string") continue;
+    const sourcePath = getSourcePathFromSourceUrl(hmrModule.sourceURL);
+    if (!sourcePath || sourcePath.includes("node_modules")) continue;
+    filePaths.push(sourcePath);
+  }
+};
+
+/**
+ * Extracts the updated source file paths from a raw Metro HMR WebSocket
+ * message. Paths are project-relative but extension-less (`src/app`, not
+ * `src/app.tsx`) because Metro rewrites module extensions to `.bundle`.
+ * The initial update replayed on connect is skipped. Returns an empty
+ * array for any other message shape.
+ *
+ * @example
+ * ```ts
+ * parseMetroUpdatePaths(rawMessageData);
+ * // ["src/app"]
+ * ```
+ */
+export const parseMetroUpdatePaths = (rawMessageData: string): string[] => {
+  let message: unknown;
+  try {
+    message = JSON.parse(rawMessageData);
+  } catch {
+    return [];
+  }
+  if (typeof message !== "object" || message === null) return [];
+  if (!("type" in message) || message.type !== "update") return [];
+  if (!("body" in message) || typeof message.body !== "object" || message.body === null) return [];
+  const updateBody = message.body;
+  if ("isInitialUpdate" in updateBody && updateBody.isInitialUpdate === true) return [];
+  const filePaths: string[] = [];
+  if ("added" in updateBody) collectModuleSourcePaths(updateBody.added, filePaths);
+  if ("modified" in updateBody) collectModuleSourcePaths(updateBody.modified, filePaths);
+  return filePaths;
+};
+
+export interface MetroHmrTransportOptions {
+  bundleUrl?: string;
+}
+
+/**
+ * Subscribes to the Metro dev server's `/hot` HMR WebSocket (as a second
+ * client alongside React Native's own) and invokes `onHmrUpdate` with the
+ * updated file paths on every hot update. Reconnects automatically when
+ * the dev server restarts. Returns `null` when no Metro bundle URL can be
+ * resolved (production builds, non-Metro runtimes).
+ *
+ * @example
+ * ```ts
+ * const transport = createMetroHmrTransport((filePaths) => {
+ *   console.log("hot updated:", filePaths);
+ * });
+ * transport?.dispose();
+ * ```
+ */
+export const createMetroHmrTransport = (
+  onHmrUpdate: HmrUpdateHandler,
+  options: MetroHmrTransportOptions = {},
+): HmrTransport | null => {
+  if (typeof WebSocket === "undefined") return null;
+  const bundleUrl = options.bundleUrl ?? getMetroBundleUrl();
+  if (!bundleUrl) return null;
+
+  let hotSocketUrl: string;
+  try {
+    const parsedBundleUrl = new URL(bundleUrl);
+    const socketProtocol = parsedBundleUrl.protocol === "https:" ? "wss" : "ws";
+    hotSocketUrl = `${socketProtocol}://${parsedBundleUrl.host}/hot`;
+  } catch {
+    return null;
+  }
+
+  let isDisposed = false;
+  let socket: WebSocket | null = null;
+  let reconnectTimerId: ReturnType<typeof setTimeout> | undefined;
+
+  const scheduleReconnect = () => {
+    if (isDisposed) return;
+    reconnectTimerId = setTimeout(connect, HMR_RECONNECT_DELAY_MS);
+  };
+
+  const connect = () => {
+    if (isDisposed) return;
+    const connectedSocket = new WebSocket(hotSocketUrl);
+    socket = connectedSocket;
+    connectedSocket.onopen = () => {
+      connectedSocket.send(
+        JSON.stringify({ type: "register-entrypoints", entryPoints: [bundleUrl] }),
+      );
+    };
+    connectedSocket.onmessage = (event) => {
+      const filePaths = parseMetroUpdatePaths(String(event.data));
+      if (filePaths.length > 0) onHmrUpdate(filePaths);
+    };
+    connectedSocket.onclose = scheduleReconnect;
+  };
+
+  connect();
+
+  return {
+    dispose: () => {
+      isDisposed = true;
+      clearTimeout(reconnectTimerId);
+      if (socket) {
+        socket.onclose = null;
+        socket.close();
+      }
+    },
+  };
+};

package/src/react-refresh/next-webpack-hmr-transport.ts

@@ -0,0 +1,72 @@
+import { HMR_SOURCE_FILE_EXTENSION_REGEX } from "./constants.js";
+import { normalizeHmrFilePath } from "./normalize-hmr-file-path.js";
+import { HmrTransport, HmrUpdateHandler } from "./types.js";
+
+interface WebpackHotUpdateGlobal {
+  (chunkId: unknown, updatedModules: Record<string, unknown> | undefined, runtime: unknown): void;
+}
+
+declare global {
+  interface Window {
+    webpackHotUpdate_N_E?: WebpackHotUpdateGlobal;
+  }
+}
+
+/**
+ * Normalizes webpack hot-update module keys into project-relative source
+ * file paths, dropping node_modules entries and non-source keys (e.g.
+ * webpack runtime helpers).
+ *
+ * @example
+ * ```ts
+ * normalizeWebpackModulePaths(["(app-pages-browser)/./app/page.tsx"]);
+ * // ["app/page.tsx"]
+ * ```
+ */
+export const normalizeWebpackModulePaths = (moduleKeys: string[]): string[] => {
+  const filePaths: string[] = [];
+  for (const moduleKey of moduleKeys) {
+    if (moduleKey.includes("node_modules")) continue;
+    const filePath = normalizeHmrFilePath(moduleKey);
+    if (!HMR_SOURCE_FILE_EXTENSION_REGEX.test(filePath)) continue;
+    filePaths.push(filePath);
+  }
+  return filePaths;
+};
+
+/**
+ * Subscribes to Next.js webpack hot updates by wrapping the
+ * `webpackHotUpdate_N_E` global and invokes `onHmrUpdate` with the updated
+ * file paths. Returns `null` when the page is not a Next.js webpack dev
+ * build.
+ *
+ * @example
+ * ```ts
+ * const transport = createNextWebpackHmrTransport((filePaths) => {
+ *   console.log("hot updated:", filePaths);
+ * });
+ * transport?.dispose();
+ * ```
+ */
+export const createNextWebpackHmrTransport = (
+  onHmrUpdate: HmrUpdateHandler,
+): HmrTransport | null => {
+  if (typeof window === "undefined") return null;
+  const originalHotUpdate = window.webpackHotUpdate_N_E;
+  if (typeof originalHotUpdate !== "function") return null;
+
+  const wrappedHotUpdate: WebpackHotUpdateGlobal = (chunkId, updatedModules, runtime) => {
+    const filePaths = normalizeWebpackModulePaths(Object.keys(updatedModules ?? {}));
+    if (filePaths.length > 0) onHmrUpdate(filePaths);
+    originalHotUpdate(chunkId, updatedModules, runtime);
+  };
+  window.webpackHotUpdate_N_E = wrappedHotUpdate;
+
+  return {
+    dispose: () => {
+      if (window.webpackHotUpdate_N_E === wrappedHotUpdate) {
+        window.webpackHotUpdate_N_E = originalHotUpdate;
+      }
+    },
+  };
+};

package/src/react-refresh/normalize-hmr-file-path.ts

@@ -0,0 +1,24 @@
+import { normalizeFileName } from "../source/get-source.js";
+
+import { BUNDLER_LAYER_PREFIX_REGEX } from "./constants.js";
+
+/**
+ * Normalizes a bundler module key or HMR update path into a plain,
+ * project-relative file path. Strips URL schemes (via
+ * {@link normalizeFileName}), bundler layer prefixes like
+ * `(app-pages-browser)/`, and leading `./` segments.
+ *
+ * @example
+ * ```ts
+ * normalizeHmrFilePath("(app-pages-browser)/./app/page.tsx");
+ * // "app/page.tsx"
+ * ```
+ */
+export const normalizeHmrFilePath = (filePath: string): string => {
+  let normalizedFilePath = normalizeFileName(filePath);
+  normalizedFilePath = normalizedFilePath.replace(BUNDLER_LAYER_PREFIX_REGEX, "");
+  if (normalizedFilePath.startsWith("./")) {
+    normalizedFilePath = normalizedFilePath.slice(2);
+  }
+  return normalizedFilePath;
+};

package/src/react-refresh/types.ts

@@ -0,0 +1,7 @@
+export interface HmrUpdateHandler {
+  (filePaths: string[]): void;
+}
+
+export interface HmrTransport {
+  dispose: () => void;
+}