[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';

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';

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';

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';

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';

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';

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';

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';