[pull] main from react:main

packages/react-devtools-cdt-mcp/README.md

@@ -3,21 +3,29 @@
 Integrates React tools with
 [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp).
 
-Importing this package **before React** installs the DevTools hook and registers
-a React tool group via chrome-devtools-mcp's `devtoolstooldiscovery` / `__dtmcp`
-third-party-tool protocol. The React tools then become discoverable and callable
-inside a chrome-devtools-mcp session — no separate server.
+Importing `react-devtools-cdt-mcp/register` **before React** installs the
+DevTools hook and registers a React tool group via chrome-devtools-mcp's
+`devtoolstooldiscovery` / `__dtmcp` third-party-tool protocol. The React tools
+then become discoverable and callable inside a chrome-devtools-mcp session — no
+separate server.
 
 ## Usage
 
-Import the package **before** React so the hook is installed before React
-initializes:
+Import the register entry **before** React so the hook is installed before
+React initializes:
 
 ```js
-import 'react-devtools-cdt-mcp';
+import 'react-devtools-cdt-mcp/register';
 import React from 'react';
 ```
 
+The package root is side-effect-free and exports the lower-level API for custom
+targets:
+
+```js
+import {register, buildToolGroup} from 'react-devtools-cdt-mcp';
+```
+
 When the page runs under chrome-devtools-mcp, the React tools are listed by
 `list_3p_developer_tools` and callable either via
 `execute_3p_developer_tool({toolName, params})` or directly via `evaluate_script`

packages/react-devtools-cdt-mcp/fixtures/app/index.js

@@ -1,7 +1,7 @@
-// Import the package source first so it installs the DevTools hook and registers
-// the chrome-devtools-mcp tool group BEFORE react-dom evaluates — the hook must
-// be in place when React's renderer injects on the first commit.
-import '../../src/index.js';
+// Import the register entry first so it installs the DevTools hook and
+// registers the chrome-devtools-mcp tool group BEFORE react-dom evaluates — the
+// hook must be in place when React's renderer injects on the first commit.
+import '../../src/register.js';
 
 import * as React from 'react';
 import {createRoot} from 'react-dom/client';

packages/react-devtools-cdt-mcp/package.json

@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "index.js"
+    "index.js",
+    "register.js"
   ],
   "scripts": {
     "build": "cross-env NODE_ENV=production rollup -c rollup.config.cjs",

packages/react-devtools-cdt-mcp/register.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./dist/register.js');

packages/react-devtools-cdt-mcp/rollup.config.cjs

@@ -9,35 +9,44 @@ if (!NODE_ENV) {
   process.exit(1);
 }
 
-module.exports = {
-  input: 'src/index.js',
-  // CommonJS bundle for the npm package (referenced by the root index.js stub).
-  output: {
-    file: 'dist/index.js',
-    format: 'cjs',
-    exports: 'named',
-  },
-  treeshake: {moduleSideEffects: false},
-  plugins: [
-    nodeResolve({
-      extensions: ['.js', '.mjs'],
-    }),
-    commonjs({
-      include: /node_modules/,
-    }),
-    babel({
-      configFile: __dirname + '/../react-devtools-shared/babel.config.js',
-      babelHelpers: 'bundled',
-    }),
-    replace({
-      preventAssignment: true,
-      values: {
-        __DEV__: String(NODE_ENV === 'development'),
-        __IS_CHROME__: 'false',
-        __IS_FIREFOX__: 'false',
-        __IS_EDGE__: 'false',
-        __IS_NATIVE__: 'false',
-      },
-    }),
-  ],
-};
+const plugins = [
+  nodeResolve({
+    extensions: ['.js', '.mjs'],
+  }),
+  commonjs({
+    include: /node_modules/,
+  }),
+  babel({
+    configFile: __dirname + '/../react-devtools-shared/babel.config.js',
+    babelHelpers: 'bundled',
+  }),
+  replace({
+    preventAssignment: true,
+    values: {
+      __DEV__: String(NODE_ENV === 'development'),
+      __IS_CHROME__: 'false',
+      __IS_FIREFOX__: 'false',
+      __IS_EDGE__: 'false',
+      __IS_NATIVE__: 'false',
+    },
+  }),
+];
+
+function createBundle(input, file) {
+  return {
+    input,
+    // CommonJS bundles for the npm package (referenced by root stubs).
+    output: {
+      file,
+      format: 'cjs',
+      exports: 'named',
+    },
+    treeshake: {moduleSideEffects: false},
+    plugins,
+  };
+}
+
+module.exports = [
+  createBundle('src/index.js', 'dist/index.js'),
+  createBundle('src/register.js', 'dist/register.js'),
+];

packages/react-devtools-cdt-mcp/src/DevToolsCdtMcp.js

@@ -307,6 +307,17 @@ export type CdtMcpToolGroup = {
   tools: Array<CdtMcpTool>,
 };
 
+type Registration = {
+  facade: Facade,
+  unregister: () => void,
+};
+
+type ToolDiscoveryEvent = {
+  respondWith: (toolGroup: CdtMcpToolGroup) => void,
+};
+
+const registrations: WeakMap<any, Registration> = new WeakMap();
+
 /**
  * Build the chrome-devtools-mcp tool group from an assembled set of facade
  * tools. Each tool returns its facade result directly.
@@ -350,21 +361,35 @@ export function register(target?: any = globalThis): {
   facade: Facade,
   unregister: () => void,
 } {
+  const existingRegistration: Registration | void = registrations.get(target);
+  if (existingRegistration !== undefined) {
+    return existingRegistration;
+  }
+
   const facade = installFacade(target);
 
   let toolGroup: CdtMcpToolGroup | null = null;
-  const listener = (event: any) => {
+  const listener = (event: ToolDiscoveryEvent) => {
     if (toolGroup === null) {
       toolGroup = buildToolGroup(createTools(facade));
     }
     event.respondWith(toolGroup);
   };
   target.addEventListener('devtoolstooldiscovery', listener);
 
-  return {
+  let isRegistered = true;
+  const registration: Registration = {
     facade,
     unregister: () => {
+      if (!isRegistered) {
+        return;
+      }
+      isRegistered = false;
       target.removeEventListener('devtoolstooldiscovery', listener);
+      registrations.delete(target);
     },
   };
+
+  registrations.set(target, registration);
+  return registration;
 }

packages/react-devtools-cdt-mcp/src/__tests__/DevToolsCdtMcp-test.js

@@ -94,6 +94,165 @@ describe('react-devtools-cdt-mcp', () => {
     expect(globalThis.__dtmcp).toBeUndefined();
   });
 
+  it('root entry exports tools without registering', () => {
+    unregister();
+    delete globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    jest.resetModules();
+
+    const api = require('../index');
+
+    expect(typeof api.register).toBe('function');
+    expect(typeof api.buildToolGroup).toBe('function');
+    expect(globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__).toBeUndefined();
+  });
+
+  it('throws when the register entry is imported outside an event target', () => {
+    const originalAddEventListener = globalThis.addEventListener;
+    const originalRemoveEventListener = globalThis.removeEventListener;
+
+    unregister();
+    delete globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    jest.resetModules();
+
+    try {
+      // $FlowFixMe[cannot-write]
+      globalThis.addEventListener = undefined;
+      // $FlowFixMe[cannot-write]
+      globalThis.removeEventListener = undefined;
+
+      expect(() => require('../register')).toThrow(
+        'react-devtools-cdt-mcp/register must be imported in a browser-like environment',
+      );
+      expect(globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__).toBeUndefined();
+    } finally {
+      globalThis.addEventListener = originalAddEventListener;
+      globalThis.removeEventListener = originalRemoveEventListener;
+    }
+  });
+
+  it('register entry installs the DevTools hook', () => {
+    const originalAddEventListener = globalThis.addEventListener;
+    const originalRemoveEventListener = globalThis.removeEventListener;
+    let autoListener = null;
+
+    unregister();
+    delete globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    jest.resetModules();
+
+    try {
+      // $FlowFixMe[cannot-write]
+      globalThis.addEventListener = (type, listener, options) => {
+        if (type === 'devtoolstooldiscovery') {
+          autoListener = listener;
+        }
+        return originalAddEventListener.call(
+          globalThis,
+          type,
+          listener,
+          options,
+        );
+      };
+
+      require('../register');
+
+      expect(globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__).toBeDefined();
+    } finally {
+      if (autoListener !== null) {
+        originalRemoveEventListener.call(
+          globalThis,
+          'devtoolstooldiscovery',
+          autoListener,
+        );
+      }
+      globalThis.addEventListener = originalAddEventListener;
+      globalThis.removeEventListener = originalRemoveEventListener;
+    }
+  });
+
+  it('returns the cached registration for repeated calls per target', () => {
+    let listener = null;
+    const target = {
+      addEventListener: jest.fn((type, callback) => {
+        expect(type).toBe('devtoolstooldiscovery');
+        listener = callback;
+      }),
+      removeEventListener: jest.fn(),
+    };
+
+    const first = register(target);
+    const second = register(target);
+
+    expect(target.addEventListener).toHaveBeenCalledTimes(1);
+    expect(second).toBe(first);
+    expect(second.facade).toBe(first.facade);
+
+    let firstGroup = null;
+    let secondGroup = null;
+    listener({
+      respondWith: group => {
+        firstGroup = group;
+      },
+    });
+    listener({
+      respondWith: group => {
+        secondGroup = group;
+      },
+    });
+    expect(secondGroup).toBe(firstGroup);
+
+    first.unregister();
+    expect(target.removeEventListener).toHaveBeenCalledTimes(1);
+    expect(target.removeEventListener).toHaveBeenCalledWith(
+      'devtoolstooldiscovery',
+      listener,
+    );
+
+    second.unregister();
+    expect(target.removeEventListener).toHaveBeenCalledTimes(1);
+
+    const third = register(target);
+    expect(third).not.toBe(first);
+    expect(target.addEventListener).toHaveBeenCalledTimes(2);
+    third.unregister();
+  });
+
+  it('does not write registration state to the target', () => {
+    let listener = null;
+    const existingHook = {
+      inject: jest.fn(() => 0),
+      onCommitFiberRoot: jest.fn(),
+      onPostCommitFiberRoot: jest.fn(),
+      renderers: new Map(),
+    };
+    const target = Object.preventExtensions({
+      __REACT_DEVTOOLS_GLOBAL_HOOK__: existingHook,
+      addEventListener: jest.fn((type, callback) => {
+        expect(type).toBe('devtoolstooldiscovery');
+        listener = callback;
+      }),
+      removeEventListener: jest.fn(),
+    });
+
+    const first = register(target);
+    const second = register(target);
+
+    expect(target.addEventListener).toHaveBeenCalledTimes(1);
+    expect(second).toBe(first);
+    expect(second.facade).toBe(first.facade);
+    expect(Object.keys(target).sort()).toEqual([
+      '__REACT_DEVTOOLS_GLOBAL_HOOK__',
+      'addEventListener',
+      'removeEventListener',
+    ]);
+
+    first.unregister();
+    second.unregister();
+    expect(target.removeEventListener).toHaveBeenCalledWith(
+      'devtoolstooldiscovery',
+      listener,
+    );
+  });
+
   it('builds a "react" tool group exposing every facade tool', () => {
     expect(toolGroup.name).toBe('react');
     expect(typeof toolGroup.description).toBe('string');

packages/react-devtools-cdt-mcp/src/index.js

@@ -7,10 +7,4 @@
  * @flow
  */
 
-import {register} from './DevToolsCdtMcp';
-
-// Side effect: install the facade (before React) and register the React tool
-// group for chrome-devtools-mcp. Import this module before React.
-register();
-
 export * from './DevToolsCdtMcp';