react-x11 2.52.0 → 2.54.0

package/docs/devtools.md

@@ -26,14 +26,12 @@ What you get:
 
 - the **component tree**, live as the app updates;
 - **props, hooks and state** when selecting a component, and editing any of
-  them — the edit goes through the reconciler's own override path, so the
-  app really re-renders;
+  them — the app really re-renders;
 - **highlight-on-hover** — hovering an element in the tree tints its rect
-  in the X11 window;
+  in the window;
 - **"highlight updates when components render"** — the rects that just
-  re-rendered are outlined, in DevTools' own colour ramp (teal for a first
-  render through amber for one that keeps re-rendering), fading out on the
-  backend's clock;
+  re-rendered are outlined in DevTools' own colour ramp (teal for a first
+  render through amber for one that keeps re-rendering), fading out;
 - the **element picker** — the crosshair in the DevTools toolbar. While it
   is on, the pointer belongs to DevTools: motion tints whatever is under
   it, a click selects that element in the tree, `Escape` gives up. The app
@@ -44,9 +42,8 @@ What you get:
   "host components") to have something with a style to select;
 - the Profiler's commit list and flamegraph, including **"reload and start
   profiling"**, which re-execs the app with profiling already on so the
-  mount itself is recorded. **Not** its Timeline view, which needs
-  `injectProfilingHooks` — this reconciler build does not expose it, so
-  there is nothing to enable;
+  mount itself is recorded. **Not** its Timeline view, which this reconciler
+  build does not support;
 - **DevTools' own settings** — component filters, console patching — kept
   between runs, in `$XDG_CACHE_HOME/react-x11/devtools.json`
   (`~/Library/Caches/react-x11/devtools.json` on macOS).
@@ -61,23 +58,20 @@ X app runs on a headless box). `REACT_X11_DEVTOOLS_STATE` moves the
 settings file.
 
 DevTools has no network panel — nothing in its protocol carries network
-data, and no injection would change that. For that, `node --inspect` and
-`chrome://inspect` still work alongside all of this.
+data. For that, `node --inspect` and `chrome://inspect` still work alongside
+all of this.
 
 ## Opening the source from the DevTools panel
 
 The inspected-element panel already shows where a component was written —
-`file:///…/tasks.jsx:42:7`, from the same React 19 call-site stacks
-click-to-component reads, absolute and source-mapped. Making that line
-_clickable_ is a standalone-side setting, and it has two independent
-routes:
+`file:///…/tasks.jsx:42:7`, absolute and source-mapped. Making that line
+_clickable_ is a standalone-side setting, with two independent routes:
 
 - **Spawn an editor.** The standalone launches one itself, choosing it from
-  `REACT_EDITOR` (a full command line, shell-quoted), else — on macOS — by
-  looking through `ps x` for an editor that is already running, else
-  `VISUAL`, else `EDITOR`. It knows each editor's argument style — vim
-  takes `+42`, sublime and the JetBrains editors take `file:42` — so this
-  is the route to reach for:
+  `REACT_EDITOR` (a full command line, shell-quoted), else — on macOS — an
+  editor already running, else `VISUAL`, else `EDITOR`. It knows each
+  editor's argument style (vim's `+42`, sublime's and JetBrains' `file:42`),
+  so this is the route to reach for:
 
   ```sh
   REACT_EDITOR=cursor npx react-devtools
@@ -85,158 +79,47 @@ routes:
 
 - **Open a URL.** ⚙ → General → "Open local files directly in your code
   editor", with the VS Code preset or a custom template using `{path}`,
-  `{line}` and `{column}`. The frontend turns our `file://` source into a
-  plain path before filling it in. The setting lives in the standalone's
-  own storage, not the app's.
+  `{line}` and `{column}`. The setting lives in the standalone's own
+  storage, not the app's.
 
 Both are configured where the standalone runs, which may be a different
-machine from the app. Neither is something the app can inject: the source
-location is all the backend is asked for, and it is already sent.
-Click-to-component ([click-to-component.md](click-to-component.md)) is the
-app-side answer to the same question, and the one that works when DevTools
-runs somewhere without your editor on it.
+machine from the app; the app cannot inject either.
+[Click-to-component](click-to-component.md) is the app-side answer to the same
+question, and the one that works when DevTools runs somewhere without your
+editor on it.
 
 The same backend, minus the socket, powers `react-x11/test`'s component
 inspection: `inspect()`/`setHook` in
-[testing.md](testing.md#inspectnode-and-sethook) drive the renderer
-interface the backend registers at injection, entirely in-process — no
-standalone app, no `ws`, no env variable. If a test run does set
-`REACT_X11_DEVTOOLS=1`, the two share one renderer registration (see the
-guard in `connect()`).
-
-## Watching the wire
-
-The bridge is a plain WebSocket carrying text frames of `{"event": …,
-"payload": …}` — no CDP, no binary framing. `scripts/devtools-proxy.mjs`
-sits in the middle of it and prints what goes past, decoding the packed
-`operations` arrays (the tree deltas) into readable lines:
-
-```sh
-npx react-devtools                      # terminal 1 — the real UI on :8097
-npm run devtools:proxy                  # terminal 2 — :8098 -> :8097
-REACT_X11_DEVTOOLS=1 REACT_X11_DEVTOOLS_PORT=8098 npm run examples:dashboard
-```
-
-```
- 0.008 ▲ app operations 193B
-       · renderer 1, root 1
-       · add root 1
-       · add 3 <Counter> (Function) under 2
- 0.291 ▼ devtools inspectElement {"id":3,"rendererID":1,…}
-```
-
-`--only`/`--skip` filter by event name, `--full` prints whole payloads, and
-`--jsonl FILE` appends every frame for later analysis.
+[testing.md](testing.md#inspectnode-and-sethook) run entirely in-process — no
+standalone app, no `ws`, no env variable. A test run that also sets
+`REACT_X11_DEVTOOLS=1` shares one renderer registration with them.
 
 ## How it works (and its sharp edges)
 
-`src/DevToolsIntegration.js`. When `REACT_X11_DEVTOOLS` is set, the hook is
-installed from `createRoot()` rather than at import time — a
-top-level await there would make every bundle of react-x11 ESM-only, which
-rules out a single executable ([packaging.md](packaging.md)). The ordering
-guarantee is the same: a commit can only follow a root, and there is no way
-to get one without awaiting the install. It connects the backend and
-registers the renderer via `injectIntoDevTools`.
-
-The backend never stops trying to connect — a retry timer while no UI
-listens, an open socket while one does — and either kept the process up
-after the app's last window closed. Its code runs in a scope
-(`inBackend`) where the timers it starts and the sockets it opens are
-unref'd, entered at our connect call, at its socket's close and error
-handlers, and at the timers it armed there; the globals are swapped only
-for that synchronous stretch, so the app's own `setTimeout` and
-`WebSocket` are untouched. The socket is `ws` from react-devtools-core's
-own dependencies, which is why `ws` is not a separate install.
-
-Under `react-x11 dev` the hook is installed earlier, before React Refresh
-loads: Refresh installs a stub hook where it finds none, the backend
-installs none where it finds one, and the stub cannot connect.
-
-Notes for maintainers:
-
-- **`injectIntoDevTools()` takes no arguments** in react-reconciler 0.34.
-  What it reports comes from the host config — `rendererPackageName`,
-  `rendererVersion`, `extraDevToolsConfig` — and an argument passed here is
-  ignored without a word, which is how react-x11 shipped for a while with
-  its renderer name and version quietly missing (#121). A test in
-  `test/smoke.test.js` asserts what reaches the hook, so the next
-  reconciler bump cannot repeat it.
-- react-devtools-core v7 requires `initialize()` before
-  `connectToDevTools`, exposes its API on the **default export** under
-  node ESM interop, and expects browser-ish globals (`self`, `window`) —
-  all handled in `prepare()`.
-- The Highlighter only emits `showNativeHighlight` for host instances that
-  implement `getClientRects()` returning a non-empty rect, and anything
-  with `getClientRects` is measured at mount through
-  `instance.ownerDocument.documentElement` — nodes therefore expose both
-  (see `Node.getClientRects` / the `ownerDocument` stub in
-  `src/nodes/`).
-- Highlight events arrive on the backend agent
-  (`hook.reactDevtoolsAgent`, or the `'react-devtools'` hook event);
-  `attachHighlightAgent` maps the public instance to its owning window
-  node and paints a translucent overlay.
-- **What makes the native paths run at all** is
-  `isReactNativeEnvironment()`, which the backend defines as
-  `window.document == null`. That is true for a node process with
-  `window = global`, so the backend takes React Native's route everywhere:
-  it _asks the host_ to draw the highlight and the update outlines, and to
-  drive the picker, instead of drawing into a DOM overlay of its own. Every
-  injection below is one of those asks.
-- **Update outlines**: the backend counts updates, picks each rect's colour
-  and expires it on its own clock, then emits `drawTraceUpdates`
-  (`[{node, color}]` — the whole live set, every time) and
-  `disableTraceUpdates`. `attachTraceUpdatesAgent` groups them by window
-  and hands each root the rects; `WindowNode.setTraceUpdates` is a dumb
-  overlay that replaces rather than accumulates. It schedules those redraws
-  on `requestAnimationFrame`, which node does not have — `prepare()`
-  installs an unref'd `setTimeout` shim, and without it the first traced
-  commit throws inside the backend.
-- **The picker**: with no `window.addEventListener` to install, the backend
-  emits `startInspectingNative` and waits. `attachPickerAgent` takes the
-  pointer through `setInspectHandler` (events.js) — motion, press and
-  release are answered and go no further — and calls `agent.selectNode()`
-  then `agent.stopInspectingNative(true)`. Cancelling from the DevTools
-  side arrives as a bridge message with no host-facing event, so the
-  picker also listens on `agent._bridge` directly; without that a
-  cancelled picker would keep swallowing the app's input.
-- **The style editor** needs three things and is offered only if it gets
-  them: `resolveRNStyle` (our `flattenStyle`, minus state blocks, which are
-  not editable values), `nativeStyleEditorValidAttributes`
-  (`STYLE_PROP_NAMES`), and `instance.measure(cb)` on host instances for
-  the box model — RN's contract, implemented by `Node.measure`. Edits
-  arrive as `overrideValueAtPath` on `['style']` with the value wrapped in
-  an array, which works here only because a react-x11 `style` prop already
-  takes an array.
-- **Reload and profile** is gated on a backend check that asks whether
-  synchronous XHR works, so `isReloadAndProfileSupported: true` is passed
-  explicitly. Registering a renderer does not start profiling, either — the
-  run that comes back from the restart starts it itself, before the first
-  commit, which is the only reason to restart at all.
-- `localStorage`/`sessionStorage` are **defined** on the global rather than
-  assigned: reading `global.localStorage` first is what makes node print
-  its `--localstorage-file` warning on every DevTools run.
-- **Hook names and sources need a deeper stack than V8 keeps.** React reads
-  each hook's location — and the custom-hook nesting the names come from —
-  off a stack captured at the hook dispatch, and `Error.stackTraceLimit` is
-  10 by default. A loader leaves frames of its own between the hook and its
-  call site (`tsx`, which every `npm run examples:*` goes through, costs
-  about ten), so the identifying frames fall off the end: `hookSource`
-  comes back `{fileName: null, lineNumber: null, …}`, the frontend logs
-  "Hook source code location not found", and the element shows its hooks
-  with no names and no source lines (#514). `prepare()` raises the limit to
-  50 when the bridge is enabled, and only upwards, so an app that asked for
-  more keeps it. `test/devtools-hooks.test.js` squeezes the budget and
-  asserts the names and sources still come back over the bridge.
-- **Selecting a component with hooks can blank the DevTools window.** That
-  is the standalone app's own renderer process aborting, upstream of
-  anything the host sends: it happens with every hook source complete, and
-  under runtimes with no loader at all. Turning ⚙ → Components → "Always
-  parse hook names for the selected element" off makes it intermittent
-  rather than reliable; restarting `npx react-devtools` reconnects to the
-  app, which is unaffected.
-- `test/devtools.test.js` drives the real backend over a socket for all of
-  the above; the fake-agent tests in `test/smoke.test.js` prove the drawing
-  but not that the backend still asks for it.
+The bridge is installed by `createRoot()` when `REACT_X11_DEVTOOLS` is set (by
+`react-x11 dev`, earlier, before React Refresh loads). Its socket is `ws` from
+`react-devtools-core`'s own dependencies, so `ws` is not a separate install.
+What an app can notice while it is on:
+
+- **It does not keep the process alive.** The backend's retry timer and socket
+  are unref'd, so the process still exits when the app's last window closes;
+  the app's own `setTimeout` and `WebSocket` are untouched.
+- **Browser-ish globals appear.** `self` and `window` are set to the global
+  where absent, `requestAnimationFrame`/`cancelAnimationFrame` are shimmed
+  where absent, and `localStorage`/`sessionStorage` are defined (the store
+  behind DevTools' settings file).
+- **`Error.stackTraceLimit` is raised to 50** (never lowered), because React
+  reads hook names and sources off a stack captured at each hook call and a
+  loader such as `tsx` eats the default 10 frames. Without it, hooks show with
+  no names and no source lines.
+- **Selecting a component with hooks can blank the DevTools window.** That is
+  the standalone app's own renderer process aborting, upstream of anything the
+  app sends. Turning ⚙ → Components → "Always parse hook names for the
+  selected element" off makes it intermittent rather than reliable;
+  restarting `npx react-devtools` reconnects to the app, which is unaffected.
+
+Design notes and maintainer notes:
+[design/devtools.md](../design/devtools.md#how-it-works-and-its-sharp-edges).
 
 ## Other debugging aids
 
@@ -245,6 +128,6 @@ Notes for maintainers:
 - Refs: drawn elements expose the retained node (`abs` rect, `scrollTo`,
   …); `<window>`/`<popup>` expose the live ntk window (`getContext('2d')`,
   `queryTree`, `setCursor`, …).
-- The in-process X server (`x11/lib/xserver`) renders headlessly and reads
-  pixels back — see `test/integration.test.js` for the harness pattern,
-  which is also how the README screenshots are generated.
+- The in-process X server (node-x11's `lib/xserver`) renders headlessly and
+  reads pixels back; `react-x11/test` is built on it
+  ([testing.md](testing.md#pixels)).