react-x11 0.0.1 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Andrey Sidorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,227 @@
 # react-x11
+
+[![CI](https://github.com/sidorares/react-x11/actions/workflows/ci.yml/badge.svg)](https://github.com/sidorares/react-x11/actions/workflows/ci.yml)
+
+React custom rendering where side effects are communication with an [X11
+server](https://www.x.org/wiki/Documentation/): react-like ergonomics on top
+of [ntk](https://github.com/sidorares/ntk). Build small GUI programs for the
+X Window environment (a linux desktop, or macOS +
+[XQuartz](https://www.xquartz.org/)) with your React / React Native
+experience — flexbox layout, components, hooks, synthetic events.
+
+Everything is JavaScript all the way down: ntk /
+[node-x11](https://github.com/sidorares/node-x11) implement the X11 protocol
+in pure JS (think xlib rewritten in node.js), layout is
+[yoga-layout](https://www.npmjs.com/package/yoga-layout), text shaping is
+[fontkit](https://github.com/foliojs/fontkit). `npm install` never compiles
+anything — and `npm test` doesn't even need an X server (node-x11 ships an
+in-process pure-JS X server that the tests render into and read pixels back
+from; every screenshot below was rendered that way too, by driving the real
+examples through the real event pipeline).
+
+| `examples/dashboard.jsx` — context theming, hooks | `examples/tasks.jsx` — useReducer, textinput, scrollview |
+| ------------------------------------------------- | -------------------------------------------------------- |
+| ![dashboard](docs/img/dashboard.png)              | ![tasks](docs/img/tasks.png)                             |
+
+| `examples/form.jsx` — textinput + Select | the open Select menu (a real `<popup>` window) |
+| ---------------------------------------- | ---------------------------------------------- |
+| ![form](docs/img/form.png)               | ![select menu](docs/img/select-menu.png)       |
+
+`examples/three.jsx` — a react-three-fiber-shaped scene over **indirect
+GLX**: `<mesh>`, geometries, materials, lights and a texture, drawn by
+sending the GL protocol over the X connection. No native bindings, no GPU
+driver bindings — the same "JavaScript all the way down" story as the rest.
+
+![3D over indirect GLX](docs/img/three.png)
+
+## Quick start
+
+```sh
+npm install react-x11 react
+```
+
+```jsx
+import React, { useState } from 'react';
+import { createRoot } from 'react-x11';
+
+function Counter() {
+  const [n, setN] = useState(0);
+  return (
+    <window width={240} height={120} title="counter" backgroundColor="#f4f4f4">
+      <box flexGrow={1} alignItems="center" justifyContent="center" gap={10}>
+        <text fontSize={24}>{String(n)}</text>
+        <box
+          backgroundColor="#2980b9"
+          borderRadius={6}
+          padding={8}
+          cursor="pointer"
+          onClick={() => setN(n + 1)}
+        >
+          <text color="white">+1</text>
+        </box>
+      </box>
+    </window>
+  );
+}
+
+const root = await createRoot(); // connects via $DISPLAY
+root.render(<Counter />);
+```
+
+Run it with `tsx` or any JSX-capable loader — or skip JSX entirely with
+`React.createElement` (see
+[`examples/simple-nojsx.js`](examples/simple-nojsx.js), plain node, no build
+step).
+
+## Elements
+
+Only `<window>`, `<popup>` and `<glarea>` map to real X11 windows.
+Everything else is laid out by yoga and drawn client-side into the window's
+double-buffered 2d context — see [NEXT_STEPS.md](NEXT_STEPS.md) for the architecture rationale
+and [docs/](docs/README.md) for the full API reference.
+
+| element        | what it is                                                                                                           |
+| -------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `<window>`     | a real X11 window; the flex, paint and event root                                                                    |
+| `<popup>`      | an override-redirect window at screen coordinates — menus, tooltips, dropdowns                                       |
+| `<box>`        | flex container: layout props → yoga, plus backgrounds, borders (solid/dashed, radius), overflow clipping, zIndex     |
+| `<scrollview>` | clipped, wheel-scrollable viewport with a drawn scrollbar                                                            |
+| `<text>`       | shaped, wrapped text (bidi, ligatures, font fallback); nested `<text>` elements are style spans                      |
+| `<textinput>`  | single-line editor: caret/selection via ntk's TextLayout caret API, clipboard (CLIPBOARD + X11 PRIMARY), word select |
+| `<image>`      | PNG/JPEG from `src`, natural-size aware                                                                              |
+| `<canvas>`     | escape hatch: `onDraw={(ctx, {width, height}) => …}` with ntk's canvas-like 2d context (XRender-backed)              |
+| `<markdown>`   | ntk MarkdownView: headings, tables, highlighted fences, math, mermaid; `onLink`                                      |
+| `<html>`       | ntk HtmlView: CSS cascade, block/flex layout, images; `onLink`                                                       |
+| `<svg>`        | static SVG through ntk SvgView, sized like `<image>`                                                                 |
+| `<tex>`        | a KaTeX formula (ntk `layoutTex`), intrinsically sized                                                               |
+| `<glarea>`     | an OpenGL surface over indirect GLX; the 3D scene below lives inside it                                              |
+
+Widget **components** (plain React on top of the primitives, themable via
+`ThemeProvider`): `Button`, `Checkbox`, `Radio`/`RadioGroup`, `Switch`,
+`Slider`, `ProgressBar`, `Select`, `Tooltip`, `MenuBar`/`ContextMenu` and
+`Dialog` — a modal built on `<popup trapFocus>`, which traps Tab and
+restores focus when it closes. See [docs/components.md](docs/components.md).
+
+### 3D
+
+Inside a `<glarea>` (or the `Canvas3D` component) the children are scene
+elements with react-three-fiber's names:
+
+```jsx
+<Canvas3D flexGrow={1} camera={{ position: [0, 2, 6], fov: 45 }}>
+  <ambientLight intensity={0.35} />
+  <pointLight position={[5, 6, 6]} />
+  <mesh rotation={[0.5, 0.4, 0]} onClick={() => pick()}>
+    <boxGeometry args={[1.4, 1.4, 1.4]} />
+    <meshPhongMaterial color="#2980b9" shininess={60} />
+  </mesh>
+</Canvas3D>
+```
+
+`<mesh>`, `<group>`, box/plane/sphere/cylinder/torus geometries,
+`<bufferGeometry>`, basic/Lambert/Phong materials with textures, four light
+types, and pointer events resolved by client-side raycasting. Each geometry
+is compiled into a **server-side display list** once, so a frame costs
+matrices plus one `CallList` per mesh whatever the triangle count. What the
+protocol cannot do — shaders, instancing, post-processing, shadows — throws
+with the reason rather than half-working. See
+[docs/elements.md](docs/elements.md#3d-scene-mesh-group-geometries-materials)
+and [docs/glx-plan.md](docs/glx-plan.md).
+
+Events are synthetic with capture/bubble phases and hit testing over the
+drawn tree: `onClick` (with DOM-style `detail` click counting),
+`onMouseDown/Up/Move`, `onMouseEnter/Leave`, `onWheel`, `onKeyDown/Up`,
+`focusable` + `onFocus`/`onBlur` + Tab traversal, and a `cursor` prop.
+User handlers run before element default actions and can
+`ev.preventDefault()` — stopping a `<textinput>` from editing or a
+`<scrollview>` from scrolling, like the DOM.
+
+## Examples
+
+All need an X server (`DISPLAY` set; XQuartz on macOS, Xvfb for automation):
+
+```sh
+npm run examples:simple        # hello world (JSX via tsx)
+npm run examples:simple-nojsx  # the same, plain node — no build step
+npm run examples:xeyes         # canvas drawing + hooks
+npm run examples:dashboard     # context theming, custom hooks, components
+npm run examples:tasks         # useReducer, textinput, scrollview
+npm run examples:menu          # right-click context menu via <popup>
+npm run examples:form          # <textinput> + Select dropdowns
+npm run examples:gl            # raw GL in a <glarea> (display-list cube)
+npm run examples:three         # <Canvas3D> scene: meshes, lights, textures
+```
+
+The two GL examples additionally need a server with **indirect GLX**
+enabled (`+iglx` / `AllowIndirectGLX` — off by default on many).
+
+### Hot reloading
+
+```sh
+npm run examples:tasks:hot     # then edit examples/tasks.jsx while it runs
+```
+
+Runs the tasks example under
+[hot-module-replacement](https://github.com/sidorares/hot-module-replacement)'s
+ESM hooks (Node ≥ 22.15) with React **Fast Refresh**: saving
+`examples/tasks.jsx` updates the edited components in place. The X11
+connection, the mounted window, and component state — the task list, even
+half-typed text in the input — survive the reload (a component whose hook
+signature changed remounts alone). `examples/hmr-register.mjs` wires up the
+transform half (babel JSX + react-refresh, chained under the HMR hooks),
+`examples/hmr-refresh.js` the runtime half, and `examples/tasks-hot.jsx` is
+the hot entry — the pattern works for any example split the same way.
+
+## React DevTools
+
+```sh
+npx react-devtools                                # 1. start the standalone UI
+REACT_X11_DEVTOOLS=1 npm run examples:dashboard   # 2. run any example with the bridge on
+```
+
+The component tree, props and hook state show up live in the DevTools
+window; selecting a component inspects it, and hovering an element in the
+tree tints its rect in the X11 window (highlight-on-hover).
+`REACT_X11_DEVTOOLS_HOST` / `REACT_X11_DEVTOOLS_PORT` override the default
+`localhost:8097`. See [docs/devtools.md](docs/devtools.md).
+
+Two more debugging aids:
+
+- `REACT_X11_DEBUG_LAYOUT=1` outlines every laid-out node (color = tree
+  depth) — handy when a flexbox doesn't do what you expect.
+- refs give you the retained node (`abs` rect, `scrollTo`, …) for drawn
+  elements, or the live [ntk](https://github.com/sidorares/ntk) window for
+  `<window>`/`<popup>` — the whole ntk API is a ref away.
+
+## Click to component
+
+```sh
+REACT_X11_EDITOR=code npm run examples:tasks
+```
+
+Alt+Click any rendered element (Option+Click on macOS/XQuartz) 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).
+
+## Developing
+
+```sh
+npm test             # hermetic: mock smoke tests + in-process X server pixels
+npm run lint         # ESLint
+npm run format       # Prettier
+npm run screenshots  # regenerate docs/img/*.png headlessly (no X server)
+```
+
+`docs/img/three.png` is the exception: the headless path has no GL, so the
+3D shot is captured by hand from `npm run examples:three` on a real server
+with indirect GLX.
+
+See [AGENTS.md](AGENTS.md) for architecture notes and contributor/agent
+guidance, [docs/](docs/README.md) for API documentation, and
+[NEXT_STEPS.md](NEXT_STEPS.md) for the roadmap.
+
+# See also
+
+https://github.com/chentsulin/awesome-react-renderer

package/package.json

@@ -1,23 +1,76 @@
 {
   "name": "react-x11",
-  "version": "0.0.1",
+  "version": "1.2.0",
   "description": "react renderer with X11 as a target",
-  "main": "test.js",
+  "main": "./src/index.js",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "examples:simple": "tsx examples/simple.jsx",
+    "examples:simple-nojsx": "node examples/simple-nojsx.js",
+    "examples:xeyes": "tsx examples/xeyes.jsx",
+    "examples:dashboard": "tsx examples/dashboard.jsx",
+    "examples:tasks": "tsx examples/tasks.jsx",
+    "examples:tasks:hot": "node --enable-source-maps --import ./examples/hmr-register.mjs examples/tasks-hot.jsx",
+    "examples:menu": "tsx examples/menu.jsx",
+    "examples:form": "tsx examples/form.jsx",
+    "examples:richtext": "tsx examples/richtext.jsx",
+    "examples:widgets": "tsx examples/widgets.jsx",
+    "examples:gl": "tsx examples/gl.jsx",
+    "examples:three": "tsx examples/three.jsx",
+    "examples:windows": "tsx examples/windows.jsx",
+    "screenshots": "tsx scripts/screenshots.jsx",
+    "screenshots:framed": "tsx scripts/screenshots-framed.jsx",
+    "bench": "tsx scripts/bench/protocol.js"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/sidorares/react-x11"
+    "url": "git+https://github.com/sidorares/react-x11.git"
   },
   "keywords": [
     "react",
     "renderer",
+    "desktop",
     "x11",
     "ui"
   ],
-  "author": "Andrey Sidorov <sidorares@yandex.ru>",
+  "author": "Andrey Sidorov <andrey.sidorov@gmail.com>",
   "license": "MIT",
+  "engines": {
+    "node": ">=20.19"
+  },
   "dependencies": {
-    "css-layout": "0.0.2",
-    "node-jsx": "^0.13.3",
-    "ntk": "sidorares/ntk"
+    "ntk": "^3.7.2",
+    "react-reconciler": "^0.33.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "overrides": {
+    "brace-expansion": "^5.0.8"
+  },
+  "devDependencies": {
+    "@babel/core": "^8.0.1",
+    "@babel/plugin-transform-react-jsx": "^8.0.1",
+    "@eslint/js": "^9.32.0",
+    "eslint": "^9.32.0",
+    "eslint-plugin-react": "^7.37.5",
+    "globals": "^16.0.0",
+    "hot-module-replacement": "^4.0.0",
+    "prettier": "^3.6.0",
+    "react": "^19.2.8",
+    "react-devtools-core": "^7.0.1",
+    "react-refresh": "^0.18.0",
+    "tsx": "^4.23.1",
+    "ws": "^8.21.1"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
   }
 }

package/src/ClickToComponent.js

@@ -0,0 +1,179 @@
+// Click-to-component: Alt+Click a rendered element to open the exact JSX
+// line that created it in your editor. Opt-in via REACT_X11_CLICK_TO_COMPONENT
+// (see docs/click-to-component.md); wired up from Reconciler.js the same way
+// REACT_X11_DEVTOOLS wires up DevToolsIntegration.js.
+//
+// Unlike DOM click-to-component tools this needs no babel/jsx-source plugin
+// and no source-map resolution of its own: React 19 already captures a real
+// `Error` (fiber._debugStack) at every JSX call site in development mode,
+// and Node's `--enable-source-maps` (which tsx and this repo's hot-reload
+// 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 { fileURLToPath } from 'node:url';
+import { setClickToComponentHandler } from './events.js';
+
+const STACK_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?\s*$/;
+
+/** The first stack frame outside React/the reconciler/node internals — the
+ * user's own JSX call site for whatever element this Error was captured at. */
+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;
+    if (
+      rawFile.includes('/node_modules/') ||
+      rawFile.startsWith('node:') ||
+      rawFile === '<anonymous>'
+    ) {
+      continue;
+    }
+    const file = rawFile.startsWith('file://')
+      ? fileURLToPath(rawFile)
+      : rawFile;
+    return {
+      functionName,
+      file,
+      line: Number(lineStr),
+      column: Number(columnStr),
+    };
+  }
+  return null;
+}
+
+function componentName(fiber) {
+  const owner = fiber._debugOwner;
+  const type = owner?.type;
+  if (type) return type.displayName || type.name || '(anonymous)';
+  return typeof fiber.type === 'string' ? `<${fiber.type}>` : '(unknown)';
+}
+
+/** Alt+Shift+Click: who-rendered-who, from the clicked element up to the
+ * root, each with its own source location — handy when the immediate owner
+ * isn't the component you meant (a shared wrapper, a list item, ...). */
+function logOwnerChain(fiber) {
+  const chain = [];
+  for (let owner = fiber._debugOwner; owner; owner = owner._debugOwner) {
+    const location = resolveLocation(owner._debugStack);
+    const name = owner.type?.displayName || owner.type?.name || '(anonymous)';
+    chain.push(
+      location
+        ? `${name} (${location.file}:${location.line}:${location.column})`
+        : name,
+    );
+  }
+  if (chain.length > 0) {
+    console.log('[click-to-component] owner chain:\n  ' + chain.join('\n  '));
+  }
+}
+
+// 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)];
+  }
+  const child = spawn(bin, args, { detached: true, stdio: 'ignore' });
+  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.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) {
+  const root = node?.root;
+  if (typeof root?.setHighlight !== 'function') return;
+  root.setHighlight(node);
+  setTimeout(() => root.setHighlight(null), 300);
+}
+
+function handleClick(node, native) {
+  const fiber = node?._reactFiber;
+  if (!fiber) {
+    console.warn(
+      'react-x11: click-to-component — this element has no fiber info.',
+    );
+    return;
+  }
+  const location = resolveLocation(fiber._debugStack);
+  if (!location) {
+    console.warn(
+      'react-x11: click-to-component — no source location found. This needs ' +
+        'React running in development mode (fiber._debugStack).',
+    );
+    return;
+  }
+  console.log(
+    `[click-to-component] ${componentName(fiber)} → ` +
+      `${location.file}:${location.line}:${location.column}`,
+  );
+  if (native?.buttons & 1) {
+    // Alt+Shift+Click
+    logOwnerChain(fiber);
+  }
+  flashHighlight(node);
+  openInEditor(location);
+}
+
+// The bit checked in events.js is X11's Mod1Mask either way — this is only
+// about what the user actually has to press. XQuartz maps the Option key to
+// Mod1 by default ("Option keys send Alt_L and Alt_R" in its Input
+// preferences); everywhere else Mod1 is the physical Alt key.
+const MODIFIER_LABEL = process.platform === 'darwin' ? 'Option' : 'Alt';
+
+export function install() {
+  setClickToComponentHandler(handleClick);
+  console.log(
+    `react-x11: click-to-component enabled — ${MODIFIER_LABEL}+Click an ` +
+      `element to open its source (${MODIFIER_LABEL}+Shift+Click also logs ` +
+      'the owner chain).',
+  );
+}

package/src/DevToolsIntegration.js

@@ -0,0 +1,106 @@
+// 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
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+let api = null;
+let connected = false;
+
+/**
+ * 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.
+ */
+export async function prepare() {
+  try {
+    // 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;
+    }
+    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;
+    api.initialize();
+  } catch (err) {
+    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: ' +
+        err.message,
+    );
+  }
+}
+
+/** 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) {
+  if (!api || connected) return;
+  connected = true;
+
+  api.connectToDevTools({
+    isAppActive: () => true,
+    host: process.env.REACT_X11_DEVTOOLS_HOST || 'localhost',
+    port: Number(process.env.REACT_X11_DEVTOOLS_PORT) || 8097,
+  });
+
+  renderer.injectIntoDevTools({
+    bundleType: 1,
+    version: require('../package.json').version,
+    rendererPackageName: 'react-x11',
+    findFiberByHostInstance: (instance) => instance._reactFiber,
+  });
+
+  watchForAgent();
+}
+
+/**
+ * Wire a DevTools backend agent's element-hover events to the renderer:
+ * hovering an element in the DevTools tree tints its rect in the window.
+ * Exported separately so it can be tested without react-devtools-core.
+ */
+export function attachHighlightAgent(agent) {
+  let highlightedRoot = null;
+
+  const show = (payload) => {
+    // newer devtools versions pass an array of public instances
+    const target = Array.isArray(payload) ? payload[0] : payload;
+    // public instances are ntk windows for <window>/<popup>, nodes otherwise
+    const node = target?._reactX11Node ?? target;
+    const root = node?.root;
+    if (!root || typeof root.setHighlight !== 'function') return;
+    if (highlightedRoot && highlightedRoot !== root) {
+      highlightedRoot.setHighlight(null);
+    }
+    highlightedRoot = root;
+    root.setHighlight(node);
+  };
+
+  const hide = () => {
+    highlightedRoot?.setHighlight(null);
+    highlightedRoot = null;
+  };
+
+  agent.addListener?.('showNativeHighlight', show);
+  agent.addListener?.('hideNativeHighlight', hide);
+  agent.addListener?.('shutdown', hide);
+}
+
+function watchForAgent() {
+  const hook = global.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook) return;
+  try {
+    if (hook.reactDevtoolsAgent) {
+      attachHighlightAgent(hook.reactDevtoolsAgent);
+    } else if (typeof hook.on === 'function') {
+      // the backend emits 'react-devtools' once the agent is initialized
+      hook.on('react-devtools', (agent) => attachHighlightAgent(agent));
+    }
+  } catch {
+    // highlight support is best-effort; the tree view still works without it
+  }
+}