fix: use static import in connect module to prevent race condition (#15)

* fix: prevent race condition in connect module with static import

The connect module used a dynamic `await import('react-devtools-core')`
which created two problems:

1. The async import yielded control before `initialize()` could install
   the devtools hook, allowing react-dom to load first and miss it.

2. Vite's esbuild dep optimizer splits dynamic imports into separate CJS
   chunks that only expose a `default` export, so named destructuring of
   `{ initialize, connectToDevTools }` silently returned undefined.

Switch to a static import so initialize() runs synchronously at module
evaluation time, before any dependent modules execute. The Vite plugin's
config hook enables top-level-await support in esbuild (kept for future
use), though this fix no longer requires it.

react-devtools-core is a required peer dependency — if not installed,
the module correctly fails to load since it cannot function without it.

Fixes #14

* docs: add headed browser requirement for agent-browser usage

Headless Chromium does not properly execute ES module scripts,
preventing the devtools connect script from installing the hook
before React loads. Document that agent-browser must use --headed
mode in the SKILL.md, setup guide, and README.

Author: piotrski

.changeset/fix-connect-race-condition.md

@@ -0,0 +1,7 @@
+---
+"agent-react-devtools": patch
+---
+
+fix: prevent race condition where React loads before devtools hook is installed
+
+The connect module's dynamic `import('react-devtools-core')` yielded control before `initialize()` could install the hook, allowing react-dom to load first and miss the connection. Added top-level `await` to block dependent modules until the hook is ready, and updated the Vite plugin to enable `top-level-await` in esbuild's dep optimizer.

README.md

@@ -198,6 +198,15 @@ For Expo, the connection works automatically with the Expo dev client.
 
 To use a custom port, set the `REACT_DEVTOOLS_PORT` environment variable.
 
+## Using with agent-browser
+
+When using `agent-browser` to drive the app (e.g. for profiling interactions), you **must use headed mode**. Headless Chromium does not properly execute the devtools connect script:
+
+```sh
+agent-browser --session devtools --headed open http://localhost:5173/
+agent-react-devtools status  # Should show "Apps: 1 connected"
+```
+
 ## Using with AI Coding Assistants
 
 Add the skill to your AI coding assistant for richer context:

packages/agent-react-devtools/skills/react-devtools/SKILL.md

@@ -124,10 +124,20 @@ agent-react-devtools profile slow --limit 5
 # Compare render counts and durations to the previous run
 ```
 
+## Using with agent-browser
+
+When using `agent-browser` to drive the app while profiling or debugging, you **must use headed mode** (`--headed`). Headless Chromium does not execute ES module scripts the same way as a real browser, which prevents the devtools connect script from running properly.
+
+```bash
+agent-browser --session devtools --headed open http://localhost:5173/
+agent-react-devtools status  # Should show 1 connected app
+```
+
 ## Important Rules
 
 - **Labels reset** when the app reloads or components unmount/remount. Always re-check with `get tree` or `find` after a page reload.
 - **`status` first** — if status shows 0 connected apps, the React app is not connected. The user may need to run `npx agent-react-devtools init` in their project first.
+- **Headed browser required** — if using `agent-browser`, always use `--headed` mode. Headless Chromium does not properly load the devtools connect script.
 - **Profile while interacting** — profiling only captures renders that happen between `profile start` and `profile stop`. Make sure the relevant interaction happens during that window.
 - **Use `--depth`** on large trees — a deep tree can produce a lot of output. Start with `--depth 3` or `--depth 4` and go deeper only on the subtree you care about.
 

packages/agent-react-devtools/skills/react-devtools/references/setup.md

@@ -98,3 +98,16 @@ If `Apps: 0 connected`:
 1. Check the app is running in dev mode
 2. Check the console for WebSocket connection errors
 3. Ensure no other DevTools instance is using port 8097
+4. If using `agent-browser`, make sure you're using **headed mode** (`--headed`) — headless Chromium does not properly execute the devtools connect script
+
+## Using with agent-browser
+
+When automating the browser with `agent-browser`, you must use headed mode. Headless Chromium handles ES module script execution differently, which prevents the connect script from installing the devtools hook before React loads.
+
+```bash
+# Headed mode is required for devtools to connect
+agent-browser --session devtools --headed open http://localhost:5173/
+
+# Verify connection
+agent-react-devtools status
+```

packages/agent-react-devtools/src/connect.ts

@@ -5,13 +5,25 @@
  *
  * This must be imported before React loads. It:
  * 1. Removes the Vite plugin-react hook stub
- * 2. Initializes react-devtools-core
+ * 2. Initializes react-devtools-core (installs the real __REACT_DEVTOOLS_GLOBAL_HOOK__)
  * 3. Connects via WebSocket to the agent-react-devtools daemon
  *
+ * Steps 1–2 run synchronously at module evaluation time via a static import
+ * of react-devtools-core. This is critical — a dynamic import would yield
+ * control and let React load before the hook is installed. The static import
+ * also ensures esbuild's CJS-to-ESM interop provides proper named exports
+ * (dynamic imports to CJS chunks only expose a default export).
+ *
+ * react-devtools-core is a required peer dependency. If not installed, this
+ * module will fail to load — which is the correct behavior since there's
+ * nothing useful it can do without it.
+ *
  * Export `ready` — a promise that resolves once the WebSocket opens
  * (or after a 2s timeout / error, so the app is never blocked).
  */
 
+import { initialize, connectToDevTools } from 'react-devtools-core';
+
 function getMeta(name: string): string | null {
   if (typeof document === 'undefined') return null;
   const meta = document.querySelector(`meta[name="${name}"]`);
@@ -41,23 +53,27 @@ const isProd =
   (typeof process !== 'undefined' &&
     process.env?.NODE_ENV === 'production');
 
+// Install the devtools hook synchronously before React loads.
+// This MUST happen at module evaluation time — if deferred to an async
+// callback, react-dom may initialize first and miss the hook entirely.
+if (!isSSR && !isProd) {
+  // Remove Vite's plugin-react hook stub so react-devtools-core can install the full hook
+  try {
+    delete (window as any).__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  } catch {
+    // Property may be non-configurable (browser extension) — ignore
+  }
+
+  initialize();
+}
+
 export const ready: Promise<void> = isSSR || isProd ? noop() : connect();
 
-async function connect(): Promise<void> {
+function connect(): Promise<void> {
   try {
     const port = getPort();
     const host = getHost();
 
-    // Remove Vite's plugin-react hook stub so react-devtools-core can install the full hook
-    try {
-      delete (window as any).__REACT_DEVTOOLS_GLOBAL_HOOK__;
-    } catch {
-      // Property may be non-configurable (browser extension) — ignore
-    }
-
-    const { initialize, connectToDevTools } = await import('react-devtools-core');
-    initialize();
-
     return new Promise<void>((resolve) => {
       try {
         const ws = new WebSocket(`ws://${host}:${port}`);
@@ -70,6 +86,6 @@ async function connect(): Promise<void> {
       }
     });
   } catch {
-    // react-devtools-core not installed or other error — silently skip
+    return Promise.resolve();
   }
 }

packages/agent-react-devtools/src/vite-plugin.ts

@@ -14,6 +14,20 @@ export function reactDevtools(options?: ReactDevtoolsOptions): Plugin {
   return {
     name: 'agent-react-devtools',
     apply: 'serve',
+    config() {
+      // The connect module uses top-level await to block React from loading
+      // before the devtools hook is installed. Vite's dep optimizer uses
+      // esbuild which defaults to es2020 (no TLA support), so we enable it.
+      return {
+        optimizeDeps: {
+          esbuildOptions: {
+            supported: {
+              'top-level-await': true,
+            },
+          },
+        },
+      };
+    },
     transformIndexHtml: {
       order: 'pre',
       handler() {