react-x11 2.52.0 → 2.53.0

package/docs/ecosystem/dev-tooling.md

@@ -1,11 +1,8 @@
 # Developer tooling
 
-This is the payoff of a pure-JS stack: a react-x11 app is an ordinary Node
-process, so the whole V8 and React tooling story applies unmodified. Nothing
-on this page needs an adapter.
-
-The four tools answer four different questions, and it is worth knowing which
-is which before you reach for one:
+A react-x11 app is an ordinary Node process, so V8 and React tooling apply
+unmodified; nothing here needs an adapter. Which tool answers which
+question:
 
 | Question                                       | Tool                                             |
 | ---------------------------------------------- | ------------------------------------------------ |
@@ -14,21 +11,19 @@ is which before you reach for one:
 | Where did the milliseconds go?                 | [`node --inspect`](#node-inspect), [`0x`](#0x)   |
 | Why is memory growing?                         | [`node --inspect`](#node-inspect) heap snapshots |
 
-`react-scan` is not on this page: its documented entry point does not resolve
-under bare Node, and its programmatic API silently never fires. See the
-[negative-results register](../ecosystem.md#silent-failures). React's own
-`<Profiler>` works unchanged under react-x11 and covers the same ground for
-commit timings.
+`react-scan` does not work: its documented entry point does not resolve
+under bare Node, and its programmatic API silently never fires
+([register](../ecosystem.md#silent-failures)). React's own `<Profiler>`
+works unchanged and covers commit timings.
 
 ## React DevTools {#react-devtools}
 
 **Out of the box — already wired behind an env var.** react-devtools-core@7.0.1.
 
-`react-devtools-core` is the backend half of React DevTools, made for exactly
-this situation: a React tree running outside a browser page. It connects over
-WebSocket to the standalone DevTools UI and streams the fiber tree, props,
-hooks and profiler data. The integration lives in
-`src/DevToolsIntegration.js` and costs nothing when off.
+`react-devtools-core` is the DevTools backend for a React tree outside a
+browser page: it connects over WebSocket to the standalone DevTools UI and
+streams the fiber tree, props, hooks and profiler data. It costs nothing
+when off.
 
 ```sh
 npm i -D react-devtools-core
@@ -40,39 +35,35 @@ npx react-devtools
 REACT_X11_DEVTOOLS=1 npm run examples:dashboard
 ```
 
-`src/Reconciler.js` checks `REACT_X11_DEVTOOLS` when you first call
-`render()`/`createRoot()`, and installs the DevTools global hook _before the
-first commit_ — that ordering is what makes mounted roots visible, and it
-holds because a commit can only follow a root.
-`REACT_X11_DEVTOOLS_HOST` and `REACT_X11_DEVTOOLS_PORT` point the backend at
-a UI elsewhere, which is useful when the app runs on a headless box next to
-the X server.
+`REACT_X11_DEVTOOLS` is read on the first `render()`/`createRoot()`, which
+installs the DevTools hook before the first commit, so every mounted root is
+visible. `REACT_X11_DEVTOOLS_HOST` and `REACT_X11_DEVTOOLS_PORT` point the
+backend at a UI elsewhere — useful when the app runs on a headless box next
+to the X server.
 
-Working today: the live component tree, props/hooks/state inspection, and
+Working: the live component tree, props/hooks/state inspection, and
 highlight-on-hover — hovering an element in the tree tints its rect in the
-X11 window. See [devtools](../devtools.md) for the full walkthrough.
+window. See [devtools](../devtools.md) for the full walkthrough.
 
-- **Start the standalone UI first**, or wait for the backend's retry. The app
-  side retries; the UI side does not attach to an already-running app unless
+- **Start the standalone UI first**, or wait for the backend's retry. The
+  app side retries; the UI does not attach to an already-running app unless
   the hook was installed at startup, and `REACT_X11_DEVTOOLS` cannot be
   turned on after the fact.
-- The Profiler's commit-oriented views (flamegraph, ranked) work with the dev
-  reconciler. The **Timeline** view cannot — it needs `injectProfilingHooks`,
-  which react-reconciler 0.33 does not expose at all.
-- `injectIntoDevTools` takes zero arguments in react-reconciler 0.33, so the
-  config object passed to it is silently discarded and
-  `findFiberByHostInstance` is never registered — DevTools cannot map a host
-  node back to its fiber. The tree, props and highlight features do not need
-  it. Do not add options to that call expecting them to do anything; the
-  supported channel is `extraDevToolsConfig` on the host config.
+- The Profiler's commit-oriented views (flamegraph, ranked) work with the
+  dev reconciler. The **Timeline** view does not — it needs
+  `injectProfilingHooks`, which react-reconciler 0.33 does not expose.
+- DevTools cannot map a host node back to its fiber
+  (`findFiberByHostInstance` is never registered); the tree, props and
+  highlight do not need it.
+
+Design notes: [design/ecosystem/dev-tooling.md](../../design/ecosystem/dev-tooling.md).
 
 ## react-refresh {#react-refresh}
 
 **Supported — `react-x11 dev` is the command, and `react-x11/refresh` the
-entry point under it.** Fast Refresh without a bundler: edit a component,
-and the mounted window updates in place with hook state intact. The X
-connection, the window, the task list, half-typed text in an input — all
-survive.
+entry point under it.** Fast Refresh without a bundler: edit a component and
+the mounted window updates in place with hook state intact — the
+connection, the window, half-typed text in an input all survive.
 
 ```sh
 npx react-x11 dev app.jsx
@@ -89,13 +80,13 @@ its work by rendering the app to a PNG in light and dark
 
 ### `react-x11 dev` {#react-x11-dev}
 
-The package's `bin`, and the route with nothing to set up. What it does,
-each because the bare loader leaves it to the app:
+The package's `bin`, with nothing to set up. What it does that the bare
+loader leaves to the app:
 
 - **It is the entry, and imports the file.** The file named on node's
-  command line is the one module hot-module-replacement never watches (see
-  below), so here the file is imported instead, which makes it an ordinary
-  hot module: an app in one file reloads.
+  command line is the one module that never reloads (see below), so `dev`
+  imports yours instead, making it an ordinary hot module: an app in one
+  file reloads.
 - **It mounts the file's default export.** A file that mounts a root of its
   own while it is imported runs as it is — `dev` sees the root appear and
   mounts nothing — and then the modules it imports reload while it does
@@ -104,16 +95,15 @@ each because the bare loader leaves it to the app:
   `tsx` and `bun`; `examples/tasks.jsx` is written that way. One that mounts
   itself unguarded _and_ exports only components is told, at start, that
   every save re-runs its `createRoot` and opens another window.
-- **It supplies a `<window>` while the tree renders none.** The tree is
-  mounted as it is; a drawn element at the root throws an error with
-  `code: 'NOT_IN_WINDOW'` before anything commits, and on that `dev` mounts
-  it again inside a window titled after the file, sized to its content with
-  a 320×200 floor. Decided again on every reload: render a `<window>` and
-  `dev`'s goes (the component remounts, so its state resets — `dev` says
-  so), lose it and it comes back. A tree that renders a `<window>` _beside_
-  content in none stays wrapped, with a note saying which content needs a
-  window. Closing the window ends the process, as closing an app's primary
-  window does.
+- **It supplies a `<window>` while the tree renders none.** A drawn
+  element at the root throws an error with `code: 'NOT_IN_WINDOW'` before
+  anything commits, and `dev` then mounts the tree inside a window titled
+  after the file, sized to its content with a 320×200 floor. Decided again
+  on every reload: render a `<window>` and `dev`'s goes (the component
+  remounts, so its state resets — `dev` says so); lose it and it comes
+  back. A tree that renders a `<window>` _beside_ content in none stays
+  wrapped, with a note saying which content needs a window. Closing the
+  window ends the process.
 - **It says when a save will not reload.** A module reloads in place only
   when everything it exports is a component by React Refresh's rule — a
   capitalized name — so `export default () => …` and a module exporting a
@@ -121,11 +111,11 @@ each because the bare loader leaves it to the app:
   says so, and why, when it starts, instead of leaving the first save to
   find out.
 - **It asks before it installs the toolchain.** The four packages below are
-  optional peer dependencies, so an app's users never download them; `dev`
-  finds the ones missing, pins them to the ranges react-x11 is written
-  against, and runs the project's package manager — from its lockfile, else
-  the one that launched `dev`, else npm — when you say yes, then starts
-  again. With no terminal to ask on it prints the command and exits.
+  optional peer dependencies, so an app's users never download them. `dev`
+  finds the missing ones, pins them to react-x11's ranges, and on a yes runs
+  the project's package manager (from its lockfile, else the one that
+  launched `dev`, else npm) and starts again. With no terminal to ask on, it
+  prints the command and exits.
 - **It connects to [React DevTools](#react-devtools)** whenever
   `npx react-devtools` is running, started before the app or after it —
   wherever `react-devtools-core` is installed. Where it is not, and a
@@ -134,48 +124,44 @@ each because the bare loader leaves it to the app:
 - **It turns on [click-to-component](../click-to-component.md).**
   Alt+Click (Option+Click on macOS) an element and its JSX line opens in
   your editor. `REACT_X11_CLICK_TO_COMPONENT=0` turns it off.
-- **It runs the project's react-x11.** A second copy of the renderer is a
-  root nobody refreshes, so a global or npx-cached `react-x11` hands over to
-  the copy the file imports, and a file that imports none is told to
-  install it.
+- **It runs the project's react-x11.** A global or npx-cached `react-x11`
+  hands over to the copy the file imports (a second copy would be a root
+  nobody refreshes); a file that imports none is told to install it.
 
 **Errors are shown in a window**, as well as printed:
 
-- **A render error** takes the app's tree down, as it would anywhere, and a
-  window titled `app.jsx — error` stands in for it. It shows the message, the
-  components it was thrown under, the source around the line, and the
-  stack's frames — React's, Node's and react-x11's own counted rather than
-  listed. The next save tries the app again; the save that fixes it brings
-  it back, and an app that throws again is back in the window.
+- **A render error** takes the app's tree down and a window titled
+  `app.jsx — error` stands in for it: the message, the components it was
+  thrown under, the source around the line, and the stack's frames (React's,
+  Node's and react-x11's own counted rather than listed). Each save tries
+  the app again.
 - **A save that does not compile** opens the same window beside the app,
   which keeps running the module's last version with its state; it closes
   once the file compiles, or when you close it.
-- A line in it opens in your editor on a click, the way
+- Clicking a line opens it in your editor, as
   [click-to-component](../click-to-component.md) does, by
-  `REACT_X11_EDITOR` (`cursor` when it is unset).
-- A throw from an event handler leaves the app running, so it is only
-  printed, and dispatch continues.
+  `REACT_X11_EDITOR` (`cursor` when unset).
+- A throw from an event handler leaves the app running; it is only printed,
+  and dispatch continues.
 
-Stack lines point at the source's own lines, through every loader layer's
-source map; `dev` turns source maps on for you. Arguments after the file
-are the app's: `react-x11 dev app.jsx --size large` hands the app the
-`process.argv` that `node app.jsx --size large` would. `.jsx` files are
-compiled and hot; `.js` and `.mjs` run as Node runs them, and the `.jsx`
-modules they import are hot. TypeScript is not supported yet.
+Stack lines point at the source's own lines (`dev` turns source maps on).
+Arguments after the file are the app's: `react-x11 dev app.jsx --size large`
+gives the app the `process.argv` that `node app.jsx --size large` would.
+`.jsx` files are compiled and hot; `.js` and `.mjs` run as Node runs them,
+and the `.jsx` modules they import are hot. TypeScript is not supported.
 
 ### Under `--import` {#refresh-import}
 
-`dev` hosts the loader in its own process; a tool that hosts it itself —
-a workbench, a custom dev loop — registers it with `--import`:
+A tool that hosts the loader itself — a workbench, a custom dev loop —
+registers it with `--import`:
 
 ```sh
 node --enable-source-maps --import react-x11/refresh/register main.jsx
 ```
 
-The entry — the file named on the command line — is the one module that is
-**never reloaded**: hot-module-replacement starts watching a module when
-another module imports it, and nothing imports the entry. So an app written
-as one file does not reload at all, and nothing says so. Keep the entry to
+The entry — the file named on the command line — is **never reloaded**: a
+module is watched once another module imports it, and nothing imports the
+entry. So a one-file app does not reload at all, silently. Keep the entry to
 mounting, and the components in modules it imports:
 
 ```jsx
@@ -188,9 +174,8 @@ const root = await ReactX11.createRoot();
 root.render(<App />);
 ```
 
-A save that does not compile is otherwise only printed — hot-module-replacement
-catches the error, and the app keeps the module's last version — so a host
-that wants to show it subscribes to the loader:
+A save that does not compile is only printed (the app keeps the module's
+last version); a host that wants to show it subscribes to the loader:
 
 ```js
 import { onTransform } from 'react-x11/refresh/loader';
@@ -216,13 +201,12 @@ await registerRefresh({
 
 ### How it reloads {#refresh-rules}
 
-Both routes run the same loader. It instruments every `.jsx`
-module and decides per module whether it is a **refresh boundary**: a
-module whose exports are all components self-accepts, so an edit to it (or
-to anything below it with no boundary of its own) re-evaluates up to that
-module and re-renders the edited components in place. A component whose
-hook signature changed remounts alone. There are no accept handlers to
-write; the one optional seam is the reload event:
+Both routes run the same loader. A module whose exports are all components
+is a **refresh boundary**: an edit to it (or to anything below it with no
+boundary of its own) re-evaluates up to that module and re-renders the
+edited components in place. A component whose hook signature changed
+remounts alone. There are no accept handlers to write; the one optional
+seam is the reload event:
 
 ```js
 import { onReload } from 'react-x11/refresh';
@@ -232,33 +216,21 @@ onReload(({ urls, refreshed }) => {
 });
 ```
 
-Node 22.15 or newer is required, for synchronous `module.registerHooks`,
-and the toolchain rides four optional peer dependencies, which `dev` offers
-to install and `--import` expects installed:
+Node 22.15 or newer is required (for synchronous `module.registerHooks`),
+plus four optional peer dependencies, which `dev` offers to install and
+`--import` expects installed:
 
 ```sh
 npm install --save-dev @babel/core @babel/plugin-transform-react-jsx react-refresh hot-module-replacement
 ```
 
-Under the hood two loader layers stack: babel (classic JSX transform plus
-`react-refresh/babel`) instruments the components, and above it
-`hot-module-replacement` rewrites static imports into live bindings and
-wires `import.meta.hot`. The runtime half patches the DevTools global hook
-before the renderer registers with it — ordering the loader guarantees by
-injecting the runtime import into every hot module's prelude. The hot
-boundary excludes `node_modules` and react-x11's own sources, so React,
-the renderer and `react-refresh/runtime` stay singletons.
-
-Each layer puts lines of its own above a module — babel's the refresh
-prelude, hot-module-replacement's a preamble — and each says so in its source
-map and composes the map of the layer beneath it. So a stack through a hot
-module points at the source's own line and column, which is what
-click-to-component opens: run Node with `--enable-source-maps`, which
-`dev` turns on itself. The composing half is hot-module-replacement
-4.0.2's, which is why that is the floor; `test/refresh-stack.test.js` fails
-on 4.0.1.
-
-The constraints are enforced errors now, not folklore:
+`node_modules` and react-x11's own sources are outside the hot boundary,
+so React, the renderer and `react-refresh/runtime` stay singletons. A stack
+through a hot module points at the source's own line and column (what
+click-to-component opens) when Node runs with `--enable-source-maps`, which
+`dev` turns on itself; this needs hot-module-replacement 4.0.2 or newer.
+
+These constraints are enforced as errors:
 
 - **A named import called at module top level inside a hot module is a
   transform error.** Named imports become live bindings initialized in a
@@ -272,54 +244,48 @@ The constraints are enforced errors now, not folklore:
   automatic runtime appends its `react/jsx-runtime` import to the last
   import's line, which the line-oriented import rewrite breaks.
 - **One statement per prelude entry.** A `prelude` entry holding two
-  statements or a newline throws, because the import rewrite replaces a
-  whole import statement's span on its line.
-
-What is _not_ enforced, so it is not rediscovered as a bug:
-
-- Under `--import`, an edit to the entry is dropped, whatever the entry
-  exports: it is never watched (above), so editing it needs a restart. An
-  edit anywhere else reaches the tree only if a boundary sits on its import
-  chain; a module whose importers lead to the entry without passing a
-  component-only module is dropped the same way. Neither says anything —
-  `dev` says the second, at start, for the file it runs.
-- **Module-scope side effects re-run on every reload** of the module and
-  of everything between it and its boundary. Keep hot modules'
-  top level idempotent, and keep identity that must survive (contexts,
-  stores) in modules outside the hot graph — via the `ignore` seam or by
-  extension. `registerElement` at module scope is safe: once the first hot
-  re-import begins, a duplicate registration replaces silently instead of
-  throwing (the
-  [re-registration policy](../extending.md#hot-reload)) — mounted nodes keep the old
-  prototype until they remount, the same staleness contract Fast Refresh
-  has for classes. Remember the named-import rule applies to it like
-  anything else: call it as `Host.registerElement(...)` through a
-  namespace or default import.
+  statements or a newline throws.
+
+Not enforced:
+
+- Under `--import`, an edit to the entry is dropped, whatever it exports;
+  editing it needs a restart. An edit elsewhere reaches the tree only if a
+  boundary sits on its import chain; a module whose importers reach the
+  entry without passing a component-only module is dropped the same way.
+  Neither says anything — `dev` reports the second, at start, for the file
+  it runs.
+- **Module-scope side effects re-run on every reload** of the module and of
+  everything between it and its boundary. Keep hot modules' top level
+  idempotent, and keep identity that must survive (contexts, stores) outside
+  the hot graph — via the `ignore` seam or by extension. `registerElement`
+  at module scope is safe: during hot reload a duplicate registration
+  replaces silently instead of throwing
+  ([re-registration policy](../extending.md#hot-reload)), and mounted nodes
+  keep the old prototype until they remount. The named-import rule applies:
+  call it as `Host.registerElement(...)` through a namespace or default
+  import.
 - Fast Refresh needs the dev reconciler; `NODE_ENV=production` is a
-  registration error. There is no production hot path, by design.
+  registration error. There is no production hot path.
 
 ## `node --inspect` {#node-inspect}
 
 **Out of the box.** Node built-in.
 
-Node's V8 inspector protocol: `node --inspect` exposes a debug port, and
-Chrome's `chrome://inspect` (or VS Code's auto-attach) connects a full
-DevTools instance — sourcemap-aware CPU profiler, heap snapshots, allocation
-timelines, live debugging.
-
-Everything that costs time in a react-x11 app is visible as ordinary JS
-frames, which is why this is the recommended profiling path:
+`node --inspect` exposes a debug port, and Chrome's `chrome://inspect` (or
+VS Code's auto-attach) connects a full DevTools instance — sourcemap-aware
+CPU profiler, heap snapshots, allocation timelines, live debugging.
+Everything that costs time in a react-x11 app is ordinary JS frames, so this
+is the recommended profiling path:
 
 - **CPU profiles of commits.** Reconciler frames (`performUnitOfWork`,
   `completeWork`), yoga layout (`calculateLayout`), style resolution and ntk
-  paint/flush show up in one call tree. That answers "is it React, layout, or
-  painting" in a single recording.
-- **Heap snapshots of retained nodes.** Every drawn element is a retained
-  node object reachable from the ntk window's `_reactX11Node`. Snapshot,
-  filter the constructor list, and leaked subtrees — a `<popup>` that never
-  unmounted, listeners held after close — are directly countable. Two
-  snapshots plus "Objects allocated between…" isolates a leak per
-  interaction.
+  paint/flush show up in one call tree: "is it React, layout, or painting"
+  in one recording.
+- **Heap snapshots of retained nodes.** Every drawn element is a node object
+  reachable from the ntk window's `_reactX11Node`, so leaked subtrees — a
+  `<popup>` that never unmounted, listeners held after close — are directly
+  countable in the constructor list. Two snapshots plus "Objects allocated
+  between…" isolates a leak per interaction.
 
 ```sh
 # interactive: profile a running app from Chrome
@@ -334,23 +300,21 @@ kill -USR1 <pid>   # inspector comes up on :9229, then attach and snapshot
 ```
 
 - **Profile with `NODE_ENV=production` when chasing React costs.** The dev
-  reconciler's stack-frame bookkeeping (`runWithFiberInDEV`) inflates commit
-  times and clutters the tree. For layout and paint costs it matters less.
-- The inspector port is an arbitrary-code-execution door. Bind it to
-  `127.0.0.1` (the default) and never expose it on a network; for remote
-  boxes, tunnel it with `ssh -L 9229:localhost:9229`.
-- This and the React DevTools Profiler are complementary: DevTools names the
-  _components_ per commit, the V8 profiler names the _functions_.
+  reconciler's bookkeeping (`runWithFiberInDEV`) inflates commit times and
+  clutters the tree; for layout and paint costs it matters less.
+- The inspector port is an arbitrary-code-execution door. Keep it on
+  `127.0.0.1` (the default); for remote boxes, tunnel it with
+  `ssh -L 9229:localhost:9229`.
+- The React DevTools Profiler names the _components_ per commit; the V8
+  profiler names the _functions_.
 
 ## `0x` {#0x}
 
 **Out of the box.** 0x@6.0.0.
 
-A single-command flamegraph generator: `0x -- node app.js` runs the process
-under the V8 sampling profiler and, on exit, writes a self-contained
-interactive `flamegraph.html`. No integration at all, and the interesting
-frames are directly searchable — `performUnitOfWork`/`completeWork`, `yoga`,
-and your own components.
+`0x -- node app.js` runs the process under the V8 sampling profiler and, on
+exit, writes a self-contained interactive `flamegraph.html`, with
+`performUnitOfWork`/`completeWork`, `yoga` and your components searchable.
 
 ```sh
 # profile an example, write the output into a throwaway dir
@@ -364,29 +328,24 @@ npx 0x --output-dir /tmp/rx11-prof -- node --import tsx examples/dashboard.jsx
 #   "Merge" view               -> collapses recursion for a cleaner ranking
 ```
 
-**Why 0x and not clinic.js:** Clinic's flame command is a wrapper around 0x,
-so for flamegraphs it adds moving parts without adding signal. Its other
-tools target server event-loop and async-I/O patterns that do not map onto a
-GUI render loop, and the package has been dormant since early 2024 while 0x
-keeps shipping.
+clinic.js's flame command wraps 0x; use 0x directly.
 
-- Sampling profiler: sub-millisecond handlers need a longer capture to show
-  up, so drive the interaction in a loop.
+- Sampling profiler: sub-millisecond handlers need a longer capture, so
+  drive the interaction in a loop.
 - Profile with `NODE_ENV=production` when measuring React itself.
-- Running through the tsx loader is fine, though frames from `.jsx` files
-  show transformed function names. Component names usually survive.
-- 0x answers "where does CPU time go", and says nothing about _which commit_
-  or _why it re-rendered_. Pair it with the DevTools Profiler and
-  why-did-you-render. For heap questions use `node --inspect`; 0x is CPU-only.
+- Under the tsx loader, frames from `.jsx` files show transformed function
+  names; component names usually survive.
+- 0x is CPU-only and says nothing about _which commit_ or _why it
+  re-rendered_; pair it with the DevTools Profiler and why-did-you-render,
+  and use `node --inspect` for heap questions.
 
 ## why-did-you-render {#why-did-you-render}
 
 **Out of the box.** @welldone-software/why-did-you-render@10.0.1.
 
-Patches the `React` namespace so that components you flag report _avoidable_
-re-renders — props or hook state that changed by reference but are equal by
-value. It hooks React itself, not `react-dom`, which is exactly why it works
-under a custom renderer.
+Patches the `React` namespace so flagged components report _avoidable_
+re-renders — props or hook state changed by reference but equal by value.
+It hooks React, not `react-dom`, so it works under any renderer.
 
 ```jsx
 import React from 'react';
@@ -411,26 +370,24 @@ const App = () => (
 // terminal: "Label … props.user: different objects that are equal by value."
 ```
 
-- Props tracking reports a re-render caused by a new-but-deep-equal object
-  prop with `diffType: 'deepEquals'` and the offending path. Hook tracking
+- A re-render caused by a new-but-deep-equal object prop is reported with
+  `diffType: 'deepEquals'` and the offending path; hook tracking
   (`trackHooks`, on by default) reports `setState` with an equal-by-value
   object the same way.
-- The default notifier prints readable `console.group` output in a terminal —
-  no browser console needed. A custom `notifier` receives the structured
-  `{displayName, reason: {propsDifferences, hookDifferences}}` object, which
-  is also how you assert on wasted renders in tests.
+- The default notifier prints `console.group` output in the terminal. A
+  custom `notifier` receives the structured
+  `{displayName, reason: {propsDifferences, hookDifferences}}` object — how
+  you assert on wasted renders in tests.
 - Works with the automatic JSX runtime as compiled by tsx and esbuild; the
-  babel alias the docs describe for webpack setups is not needed.
-- **Install it before components are defined and before the first render** —
-  the patch wraps `React.createElement` and the hook entry points on the
+  babel alias its docs describe for webpack is not needed.
+- **Install it before components are defined and before the first render**
+  — it wraps `React.createElement` and the hook entry points on the
   namespace.
-- Dev-only by design. With `NODE_ENV=production` React's prod build drops the
-  internals it reads; under plain `node`/`tsx` you get the dev build, which
-  is the right mode for it anyway.
-- Updates scheduled outside an event handler flush on a delayed task in React
-  19, so in a scripted repro, wait a macrotask before asserting the
+- Dev-only: React's production build drops the internals it reads. Plain
+  `node`/`tsx` gives the dev build.
+- Updates scheduled outside an event handler flush on a delayed task in
+  React 19, so in a scripted repro wait a macrotask before asserting the
   notification fired.
 
-This complements React DevTools: DevTools tells you _that_ a component
-rendered; why-did-you-render tells you the render was _wasted_ and which
-value to memoize.
+DevTools tells you _that_ a component rendered; why-did-you-render tells you
+the render was _wasted_ and which value to memoize.