react-x11 2.49.0 → 2.51.0

package/README.md

@@ -464,6 +464,10 @@ npx react-devtools                                # 1. start the standalone UI
 REACT_X11_DEVTOOLS=1 npm run examples:dashboard   # 2. run any example with the bridge on
 ```
 
+Under `npx react-x11 dev` the bridge is on by default (with
+`react-devtools-core` installed): run `npx react-devtools`, before or after,
+and the app shows up.
+
 The component tree, props and hook state show up live in the DevTools
 window, and editing any of them re-renders the app. Hovering an element in
 the tree tints its rect in the app's window; the toolbar's crosshair picks
@@ -498,7 +502,7 @@ Alt+Click any rendered element (Option+Click on macOS, either backend) to
 open the JSX line that created it in your editor. `REACT_X11_EDITOR` picks
 the CLI and enables the feature in one go; `REACT_X11_CLICK_TO_COMPONENT=1`
 does the same with the default editor
-(`cursor`). See [docs/click-to-component.md](docs/click-to-component.md).
+(`cursor`), and `npx react-x11 dev` turns it on by default. See [docs/click-to-component.md](docs/click-to-component.md).
 
 ## TypeScript
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.49.0",
+  "version": "2.51.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "bin": {
@@ -112,7 +112,7 @@
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.29.0",
+    "@windowkit/appkit": "^0.30.0",
     "@windowkit/wayland": "^3.1.1",
     "@windowkit/win32": "^0.0.9",
     "dbus-native": "^0.16.0",
@@ -121,7 +121,7 @@
   "peerDependencies": {
     "@babel/core": "^8.0.0",
     "@babel/plugin-transform-react-jsx": "^8.0.0",
-    "hot-module-replacement": "^4.0.1",
+    "hot-module-replacement": "^4.0.2",
     "react": "^19.3.0",
     "react-refresh": "^0.19.0"
   },
@@ -153,7 +153,7 @@
     "eslint": "^9.32.0",
     "eslint-plugin-react": "^7.37.5",
     "globals": "^17.8.0",
-    "hot-module-replacement": "^4.0.1",
+    "hot-module-replacement": "^4.0.2",
     "katex": "^0.19.0",
     "prettier": "^3.6.0",
     "react": "^19.3.0",

package/src/ClickToComponent.js

@@ -10,40 +10,9 @@
 // loader both enable) has already rewritten that Error's stack to point at
 // original source — we only have to parse the stack text and skip the
 // frames inside React/the reconciler itself.
-import { spawn } from 'node:child_process';
-import { dirname, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { setClickToComponentHandler } from './events.js';
 import { selectInDevTools } from './DevToolsIntegration.js';
-
-const STACK_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?\s*$/;
-
-// The frames to walk past before the JSX call site itself: React captures
-// the Error inside `jsxDEV`/`createElement`, and an element created by this
-// renderer (or by node internals) is never what a click means. `SELF_DIR` is
-// whichever copy of react-x11 is running — the repo's own `src/` for the
-// examples and tests, an installed `node_modules/react-x11/src` for an app.
-//
-// Everything *else* in `node_modules` is deliberately not skipped here: a
-// frame inside an installed package is a real call site, it is just not one
-// in the application's source, and telling the two apart is what lets
-// `resolveOwnedLocation` climb to the owner that is. Skipping every
-// `node_modules` frame instead would walk straight past the library
-// component and land on whatever application frame happens to be deeper in
-// the render stack — usually the `render()` call at startup, which looks
-// like an answer and isn't.
-const REACT_RUNTIME =
-  /[\\/]node_modules[\\/](react|react-dom|react-reconciler|scheduler)[\\/]/;
-const SELF_DIR = dirname(fileURLToPath(import.meta.url)) + sep;
-
-function isInternalFrame(file) {
-  return (
-    file.startsWith('node:') ||
-    file === '<anonymous>' ||
-    file.startsWith(SELF_DIR) ||
-    REACT_RUNTIME.test(file)
-  );
-}
+import { openInEditor, stackFrames } from './editor.js';
 
 /** The first stack frame outside React/the reconciler/node internals — the
  * JSX call site for whatever element this Error was captured at, wherever it
@@ -52,25 +21,16 @@ function isInternalFrame(file) {
  * Exported because `react-x11/test`'s `sourceOf` answers the same question
  * for a test that a click answers for an editor. */
 export function resolveLocation(debugStack) {
-  const stack = debugStack?.stack;
-  if (!stack) return null;
-  for (const line of stack.split('\n').slice(1)) {
-    const match = line.match(STACK_FRAME);
-    if (!match) continue;
-    const [, functionName, rawFile, lineStr, columnStr] = match;
-    const file = rawFile.startsWith('file://')
-      ? fileURLToPath(rawFile)
-      : rawFile;
-    if (isInternalFrame(file)) continue;
-    return {
-      functionName,
-      file,
-      line: Number(lineStr),
-      column: Number(columnStr),
-      installed: file.includes(`${sep}node_modules${sep}`),
-    };
-  }
-  return null;
+  const frame = stackFrames(debugStack?.stack).find((f) => !f.internal);
+  if (!frame) return null;
+  const { functionName, file, line, column, installed } = frame;
+  return {
+    functionName: functionName ?? undefined,
+    file,
+    line,
+    column,
+    installed,
+  };
 }
 
 /** The nearest source location a click can mean: the clicked element's own
@@ -132,87 +92,6 @@ function logOwnerChain(fiber) {
   }
 }
 
-// GUI editors: navigate their registered URI scheme (same idea as
-// https://github.com/sidorares/show-component, minus the browser) instead of
-// spawning their CLI shim. The CLI wrapper (e.g. `cursor -g ...`) round-trips
-// through a shell script that re-detects and re-execs the real app, which is
-// visibly slower than the OS handing the URL straight to the already-running
-// instance via Launch Services (macOS) / xdg-open (Linux).
-const EDITOR_SCHEMES = {
-  cursor: 'cursor',
-  code: 'vscode',
-  vscode: 'vscode',
-  'code-insiders': 'vscode-insiders',
-  'vscode-insiders': 'vscode-insiders',
-  windsurf: 'windsurf',
-};
-
-// Terminal editors have no URI scheme to navigate — spawn them directly.
-const EDITOR_CLI = {
-  vim: (file, line, column) => [
-    'vim',
-    [`+call cursor(${line},${column})`, file],
-  ],
-  nvim: (file, line, column) => [
-    'nvim',
-    [`+call cursor(${line},${column})`, file],
-  ],
-};
-
-const OPEN_URI_COMMAND = process.platform === 'darwin' ? 'open' : 'xdg-open';
-
-function editorUri(scheme, file, line, column) {
-  return `${scheme}://file${encodeURI(file)}:${line}:${column}`;
-}
-
-function openInEditor({ file, line, column }) {
-  const name = process.env.REACT_X11_EDITOR || 'cursor';
-  let bin, args;
-  if (EDITOR_CLI[name]) {
-    [bin, args] = EDITOR_CLI[name](file, line, column);
-  } else {
-    // an unrecognized name is assumed to be a URI scheme itself, so any
-    // editor that registers one works without a matching entry above
-    const scheme = EDITOR_SCHEMES[name] || name;
-    bin = OPEN_URI_COMMAND;
-    args = [editorUri(scheme, file, line, column)];
-  }
-  // stderr is kept (rather than the whole stdio ignored) for one reason:
-  // `open`/`xdg-open` exit non-zero and print *there* when nothing claims
-  // the scheme — an editor that isn't installed, or one whose URL handler
-  // was never registered. Swallowing that is what makes click-to-component
-  // look like it only logs: the location resolves, the console line prints,
-  // and the editor silently never opens.
-  const child = spawn(bin, args, {
-    detached: true,
-    stdio: ['ignore', 'ignore', 'pipe'],
-  });
-  let stderr = '';
-  // ...and unref'd, so keeping it does not keep the process alive: a pipe is
-  // a ref'd handle, and an editor that outlives the app it was launched from
-  // is the normal case, not a reason to hold the event loop open.
-  child.stderr.unref();
-  child.stderr.on('data', (chunk) => {
-    stderr += chunk;
-  });
-  child.on('error', (err) => {
-    console.warn(
-      `react-x11: click-to-component could not launch "${bin}" (${err.code ?? err.message}). ` +
-        'Set REACT_X11_EDITOR to your editor CLI (cursor, code, code-insiders, windsurf, vim, nvim).',
-    );
-  });
-  child.on('exit', (code) => {
-    if (!code) return;
-    console.warn(
-      `react-x11: click-to-component — \`${bin} ${args.join(' ')}\` exited ${code}. ` +
-        (stderr.trim() ? `${stderr.trim()} ` : '') +
-        `Set REACT_X11_EDITOR to the editor you actually use (currently "${name}"; ` +
-        'cursor, code, code-insiders, windsurf, vim, nvim, or any registered URI scheme).',
-    );
-  });
-  child.unref();
-}
-
 /** Briefly tint the clicked node so there is visual confirmation of what was
  * resolved, reusing the same overlay the DevTools hover highlight paints. */
 function flashHighlight(node) {

package/src/DevToolsIntegration.js

@@ -1,7 +1,8 @@
 // Opt-in React DevTools bridge. Enabled by setting REACT_X11_DEVTOOLS=1 in
-// the environment; requires the `react-devtools-core` and `ws` dev
-// dependencies. Start the standalone UI first (`npx react-devtools`), then
-// run the app: REACT_X11_DEVTOOLS=1 npm run examples:dashboard
+// the environment, and on by default under `react-x11 dev`; requires the
+// `react-devtools-core` dev dependency. Run the standalone UI
+// (`npx react-devtools`) and the app, in either order:
+// REACT_X11_DEVTOOLS=1 npm run examples:dashboard
 //
 // Most of what DevTools can do costs this file nothing: the component tree,
 // props/state/hooks, and every edit the frontend makes go through the
@@ -12,12 +13,14 @@
 // Each of those is an agent listener or an option below.
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 import { setInspectHandler } from './events.js';
 import { flattenStyle, isStyleProp, STYLE_PROP_NAMES } from './styles.js';
 
 let api = null;
+let prepared = null;
 let connected = false;
 
 // ---------------------------------------------------------------------------
@@ -107,9 +110,16 @@ export function createStorage(persist) {
 /**
  * Install the DevTools global hook. Must run before the first React commit
  * so mounted roots are observed — Reconciler.js awaits this at module load
- * when REACT_X11_DEVTOOLS is set.
+ * when REACT_X11_DEVTOOLS is set — and before React Refresh patches the
+ * hook, which `react-x11 dev` calls it early for: the backend installs no
+ * hook where one exists, and Refresh's is a stub. Once per process.
  */
-export async function prepare() {
+export function prepare() {
+  prepared ??= install();
+  return prepared;
+}
+
+async function install() {
   try {
     // Each hook's source location is read off a stack captured at the hook
     // dispatch, and V8 keeps ten frames — fewer than a loader leaves
@@ -122,9 +132,6 @@ export async function prepare() {
     // react-devtools-core's backend bundle expects browser-ish globals
     global.self ??= global;
     global.window ??= global;
-    if (!global.WebSocket) {
-      global.WebSocket = (await import('ws')).default;
-    }
     // The update-tracing overlay schedules its redraws on animation
     // frames, which Node does not have; without these the first traced
     // commit throws inside the backend. Unref'd, because an overlay must
@@ -162,6 +169,7 @@ export async function prepare() {
     const mod = await import('react-devtools-core');
     // v7 exposes the API on the default export under node ESM interop
     api = mod.default?.initialize ? mod.default : mod;
+    HostSocket = hostSocketClass();
     // The hook settings the user last chose in the DevTools UI — console
     // patching and friends. `initialize()` takes them, `onSettingsUpdated`
     // (below) records them, so a setting survives a restart.
@@ -170,7 +178,7 @@ export async function prepare() {
     api = null;
     console.warn(
       'react-x11: REACT_X11_DEVTOOLS is set but devtools could not be loaded. ' +
-        'Install react-devtools-core and ws. Original error: ' +
+        'Install react-devtools-core. Original error: ' +
         err.message,
     );
   }
@@ -254,6 +262,80 @@ export function reloadAndProfile(recordChangeDescriptions, recordTimeline) {
 // Connect
 // ---------------------------------------------------------------------------
 
+// The backend keeps trying to connect for as long as the process lives — a
+// timer every two seconds while no UI is listening, and an open socket while
+// one is — and either is enough to keep a Node process up after the app's
+// last window closed. Under `react-x11 dev`, where it is on by default, that
+// was every session hanging on close. Neither is reachable from the options:
+// so the backend's own code runs in a scope where the timers it starts are
+// unref'd and the sockets it opens are, too. The scope is entered where the
+// backend is — our connect call, its socket's close and error handlers that
+// schedule the retry, and the timers it set in the scope — and swaps the
+// globals only for that synchronous stretch, so the app's own `setTimeout`
+// and `WebSocket` are never the ones changed.
+let HostSocket = null;
+
+function inBackend(fn) {
+  const { setTimeout: appSetTimeout, WebSocket: appWebSocket } = globalThis;
+  globalThis.setTimeout = (callback, ...rest) => {
+    const timer = appSetTimeout(
+      typeof callback === 'function'
+        ? (...args) => inBackend(() => callback(...args))
+        : callback,
+      ...rest,
+    );
+    timer?.unref?.();
+    return timer;
+  };
+  if (HostSocket) globalThis.WebSocket = HostSocket;
+  try {
+    return fn();
+  } finally {
+    globalThis.setTimeout = appSetTimeout;
+    globalThis.WebSocket = appWebSocket;
+  }
+}
+
+/**
+ * The backend's WebSocket: `ws`, from react-devtools-core's own
+ * dependencies, with its socket unref'd once open and its close and error
+ * handlers run in the backend's scope. Falls back to the platform's
+ * WebSocket, which works and holds the process open.
+ */
+function hostSocketClass() {
+  let WS;
+  try {
+    WS = createRequire(import.meta.resolve('react-devtools-core'))('ws');
+  } catch {
+    return globalThis.WebSocket ?? null;
+  }
+  class Socket extends WS {
+    constructor(...args) {
+      super(...args);
+      this.on('open', () => this._socket?.unref?.());
+    }
+  }
+  for (const name of ['onclose', 'onerror']) {
+    const base = Object.getOwnPropertyDescriptor(WS.prototype, name);
+    if (!base?.set) continue;
+    Object.defineProperty(Socket.prototype, name, {
+      configurable: true,
+      get() {
+        return base.get.call(this);
+      },
+      set(handler) {
+        base.set.call(
+          this,
+          typeof handler === 'function'
+            ? (...args) => inBackend(() => handler(...args))
+            : handler,
+        );
+      },
+    });
+  }
+  return Socket;
+}
+
 /** Connect the backend to the standalone DevTools app and register the
  * renderer. Called by Reconciler.js right after the renderer is created. */
 export function connect(renderer) {
@@ -261,39 +343,41 @@ export function connect(renderer) {
   connected = true;
   const profiling = readProfilingOnStart();
 
-  api.connectToDevTools({
-    isAppActive: () => true,
-    host: process.env.REACT_X11_DEVTOOLS_HOST || 'localhost',
-    port: Number(process.env.REACT_X11_DEVTOOLS_PORT) || 8097,
-    // The style editor: `style` is a react-x11 style prop (an object, or a
-    // nested array of them), which is the shape DevTools' own resolver
-    // expects to be handed flat. `validAttributes` is what it offers to
-    // add to an element.
-    resolveRNStyle: resolveStyle,
-    nativeStyleEditorValidAttributes: STYLE_PROP_NAMES,
-    // Hook settings (console patching and so on) are the user's, not the
-    // run's: keep them where the next run will find them.
-    onSettingsUpdated: (settings) => {
-      try {
-        global.localStorage?.setItem(
-          HOOK_SETTINGS_KEY,
-          JSON.stringify(settings),
-        );
-      } catch {
-        // an unwritable store is not worth a warning per keystroke
-      }
-    },
-    // The backend's own check for this asks whether synchronous XHR works,
-    // which is a browser question — the honest answer for a node process
-    // that can re-exec itself is yes.
-    isReloadAndProfileSupported: true,
-    isProfiling: profiling != null,
-    onReloadAndProfile: reloadAndProfile,
-    onReloadAndProfileFlagsReset: () => {
-      delete process.env.REACT_X11_DEVTOOLS_PROFILING;
-      delete process.env.REACT_X11_DEVTOOLS_SESSION;
-    },
-  });
+  inBackend(() =>
+    api.connectToDevTools({
+      isAppActive: () => true,
+      host: process.env.REACT_X11_DEVTOOLS_HOST || 'localhost',
+      port: Number(process.env.REACT_X11_DEVTOOLS_PORT) || 8097,
+      // The style editor: `style` is a react-x11 style prop (an object, or a
+      // nested array of them), which is the shape DevTools' own resolver
+      // expects to be handed flat. `validAttributes` is what it offers to
+      // add to an element.
+      resolveRNStyle: resolveStyle,
+      nativeStyleEditorValidAttributes: STYLE_PROP_NAMES,
+      // Hook settings (console patching and so on) are the user's, not the
+      // run's: keep them where the next run will find them.
+      onSettingsUpdated: (settings) => {
+        try {
+          global.localStorage?.setItem(
+            HOOK_SETTINGS_KEY,
+            JSON.stringify(settings),
+          );
+        } catch {
+          // an unwritable store is not worth a warning per keystroke
+        }
+      },
+      // The backend's own check for this asks whether synchronous XHR works,
+      // which is a browser question — the honest answer for a node process
+      // that can re-exec itself is yes.
+      isReloadAndProfileSupported: true,
+      isProfiling: profiling != null,
+      onReloadAndProfile: reloadAndProfile,
+      onReloadAndProfileFlagsReset: () => {
+        delete process.env.REACT_X11_DEVTOOLS_PROFILING;
+        delete process.env.REACT_X11_DEVTOOLS_SESSION;
+      },
+    }),
+  );
 
   // No argument: react-reconciler 0.33 takes none, and the object this used
   // to pass was discarded in silence. The renderer's name and version now

package/src/Reconciler.js

@@ -592,16 +592,15 @@ let integrationsSettled = false;
 function loadIntegrations() {
   if (integrationsSettled) return null;
   if (
-    !process.env.REACT_X11_DEVTOOLS &&
-    !process.env.REACT_X11_CLICK_TO_COMPONENT &&
-    !process.env.REACT_X11_EDITOR &&
+    !envFlag('REACT_X11_DEVTOOLS') &&
+    !clickToComponentWanted() &&
     !process.env.REACT_X11_TRACE
   ) {
     return null;
   }
   if (integrations) return integrations;
   integrations = (async () => {
-    if (process.env.REACT_X11_DEVTOOLS) {
+    if (envFlag('REACT_X11_DEVTOOLS')) {
       // Install the DevTools hook before any React commit, and register the
       // renderer with the standalone DevTools app.
       const devtools = await import('./DevToolsIntegration.js');
@@ -609,12 +608,7 @@ function loadIntegrations() {
       devtools.connect(Renderer);
     }
 
-    if (
-      process.env.REACT_X11_CLICK_TO_COMPONENT ||
-      process.env.REACT_X11_EDITOR
-    ) {
-      // Naming an editor already means you want the feature on — no need to
-      // also set REACT_X11_CLICK_TO_COMPONENT=1 just to pick one.
+    if (clickToComponentWanted()) {
       const clickToComponent = await import('./ClickToComponent.js');
       clickToComponent.install();
     }
@@ -632,6 +626,28 @@ function loadIntegrations() {
   return integrations;
 }
 
+/**
+ * Whether to install click-to-component. Naming an editor already means you
+ * want the feature on — no need to also set REACT_X11_CLICK_TO_COMPONENT=1
+ * just to pick one — and `0` turns it off whatever else is set, which is
+ * the way out of `react-x11 dev`, where it is on by default and
+ * REACT_X11_EDITOR also picks the error window's editor.
+ */
+function clickToComponentWanted() {
+  if (process.env.REACT_X11_CLICK_TO_COMPONENT === '0') return false;
+  return (
+    envFlag('REACT_X11_CLICK_TO_COMPONENT') ||
+    Boolean(process.env.REACT_X11_EDITOR)
+  );
+}
+
+/** A switch in the environment: set, and not `0` — the way out of a
+ * default `react-x11 dev` turns on. */
+function envFlag(name) {
+  const value = process.env[name];
+  return Boolean(value) && value !== '0';
+}
+
 /**
  * Open a connection this process owns. The wrapper is here for one reason:
  * to say what is wrong when there is no server, which is the first thing