react-x11 2.51.1 → 2.52.0

package/docs/permissions.md

@@ -0,0 +1,148 @@
+# Permissions
+
+May this app use the camera, the microphone, the screen, the accessibility
+APIs — and how does it ask?
+
+```jsx
+import { usePermission } from 'react-x11';
+
+function RecordButton() {
+  const mic = usePermission('microphone');
+
+  if (!mic.available) return <Button label="Record" onPress={record} />;
+  if (mic.status === 'granted')
+    return <Button label="Record" onPress={record} />;
+  return (
+    <Button
+      label={mic.status === 'prompt' ? 'Allow microphone' : 'Open Settings'}
+      onPress={() =>
+        mic.status === 'prompt' ? mic.request() : mic.openSettings()
+      }
+    />
+  );
+}
+```
+
+## The ladder
+
+The [file dialog](filedialog.md)'s shape again, with one rung that answers and
+one that only points:
+
+|     |                                  |                                                                                                                                                                                                                 |
+| --- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **the platform's authorization** | The [cocoa backend](macos.md): macOS's privacy (TCC) status per kind, and the system's own prompt where a framework offers one — `AVCaptureDevice` for the camera and microphone, `CoreLocation`, and the rest. |
+| 2   | **the Settings pane**            | `open x-apple.systempreferences:…` — any Mac, bridge or not. It cannot read a status or raise a prompt; it puts the user in front of the switch, which is all `openPrivacySettings` promises.                   |
+
+**On Linux nothing answers yet.** The freedesktop counterparts are the
+per-device portals (`org.freedesktop.portal.Camera`, `.Location`, …), which
+need no bridge and are
+[#466](https://github.com/sidorares/react-x11/issues/466)'s remaining half.
+Until then a status query says `'unknown'` and a request rejects with a
+**typed** `NoPermissionServiceError` — the signal to keep the feature behind
+the answer, not a crash. `usePermission().available` is that branch as render
+state.
+
+The top rung is never chosen by naming a backend: the call asks the connection
+the tree renders through whether it has an authorization API, and the cocoa
+backend says so by carrying one.
+
+## The vocabulary
+
+```ts
+type PermissionKind =
+  | 'camera'
+  | 'microphone'
+  | 'screen-recording'
+  | 'accessibility'
+  | 'input-monitoring'
+  | 'automation'
+  | 'location'
+  | 'calendars'
+  | 'reminders';
+
+type PermissionStatus =
+  'granted' | 'denied' | 'restricted' | 'prompt' | 'write-only' | 'unknown';
+```
+
+A status is one of six words, and two of them are not the platform's:
+
+|                |                                                                                                                                                                                                                                  |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'granted'`    | use it                                                                                                                                                                                                                           |
+| `'denied'`     | the user said no; `openPrivacySettings()` is the way back                                                                                                                                                                        |
+| `'restricted'` | MDM or parental controls — the user **cannot** grant it, so no Settings button                                                                                                                                                   |
+| `'prompt'`     | not decided yet — `request()` would ask                                                                                                                                                                                          |
+| `'write-only'` | macOS 14's partial grant for `calendars` and `reminders`: the app may **save** an item it cannot read. A grant to a writer and a refusal to a reader, so it crosses as its own word rather than being flattened into one of them |
+| `'unknown'`    | nothing here can say. A fact about the machine, not the permission, and the reason a status query never throws                                                                                                                   |
+
+A request answers with the **status after the user answered**, never a bare
+boolean, because `'denied'` and `'restricted'` want different UI.
+
+## `usePermission()`
+
+```ts
+const { status, available, request, refresh, openSettings } = usePermission(kind, { target? });
+```
+
+`status` starts `'unknown'` and settles once read. `request()` resolves with
+the status after the user answered and updates `status` with it; a second call
+while one is in flight returns the same promise, so a double-clicked button
+asks once. There is **no change notification** behind a status on any
+platform — the status is what was last read, on mount and after each
+`request()`; `refresh()` re-reads it on your own cue, a window coming back to
+the front being the usual one.
+
+## The bare functions
+
+```ts
+import {
+  permissionStatus,
+  requestPermission,
+  openPrivacySettings,
+  permissionBackend,
+} from 'react-x11';
+
+await permissionStatus('camera'); // never rejects for anything about the machine
+await requestPermission('camera'); // rejects with NoPermissionServiceError where nothing can ask
+await openPrivacySettings('camera'); // true if something opened; false off macOS
+permissionBackend(); // 'cocoa' | null, synchronously
+```
+
+## What each kind actually does on macOS
+
+Not every kind has a prompt of its own, and the shape of the request follows
+the framework's:
+
+| kind                   | status                | the "prompt"                                                                                                                                        |
+| ---------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `camera`, `microphone` | all five              | the system's in-process dialog; the answer arrives when the user clicks                                                                             |
+| `screen-recording`     | never `'prompt'`      | the system's go-to-Settings dialog, shown once; the request resolves at once, and a new grant needs a **restart**                                   |
+| `accessibility`        | never `'prompt'`      | the go-to-Settings dialog; resolves at once, and the grant applies live                                                                             |
+| `input-monitoring`     | `'prompt'` while open | posts the prompt and resolves at once                                                                                                               |
+| `automation`           | per **target**        | `{ target: 'com.apple.finder' }` — the bundle id of a **running** app, or the call throws; asking blocks until answered                             |
+| `location`             | all five              | `requestWhenInUseAuthorization`, answered through the run loop                                                                                      |
+| `calendars`            | plus `'write-only'`   | EventKit's own prompt. `{ access: 'write-only' }` asks the narrower one; the grant is what [desktop-calendar.md](desktop-calendar.md) reads through |
+| `reminders`            | plus `'write-only'`   | the same store, a separate grant. `{ access: 'write-only' }` is a `TypeError` here: reminders have no such grant                                    |
+| `files-and-folders`    | —                     | no API: reading the folder _is_ the prompt and `EPERM` the denial; `openPrivacySettings` reaches the pane                                           |
+| `full-disk-access`     | —                     | no API; `openPrivacySettings('full-disk-access')`                                                                                                   |
+
+**Attribution is the thing to know.** A bare `node` process is attributed to
+its _responsible process_ — the terminal, an IDE — or to `node` itself, and
+prompts with no usage-description strings. A bundled app must carry the keys
+(`NSCameraUsageDescription`, `NSMicrophoneUsageDescription`,
+`NSLocationUsageDescription`, `NSAppleEventsUsageDescription`,
+`NSCalendarsFullAccessUsageDescription`,
+`NSCalendarsWriteOnlyAccessUsageDescription`,
+`NSRemindersFullAccessUsageDescription`) in its `Info.plist` — without them
+the request never prompts, or TCC ends the process. See
+[packaging.md](packaging.md).
+
+## What differs between the rungs
+
+- **The Settings rung reads nothing.** `openPrivacySettings` opens the pane
+  on any Mac — through the bridge on the cocoa backend, by `open` under
+  XQuartz — and that is all it does; the status stays `'unknown'` on the X11
+  backend because nothing there can read TCC.
+- **`'unknown'` is not `'prompt'`.** An app that treats them alike will show
+  an "Allow" button on Linux that rejects when pressed. Branch on `available`
+  first.

package/docs/react-features.md

@@ -0,0 +1,430 @@
+# React features
+
+You already know React. This page is about the parts where that knowledge
+transfers unchanged, the parts where it transfers with a caveat, and the
+four places where a habit from the DOM will quietly not work.
+
+The short version: **everything in React core behaves exactly as documented.**
+Hooks, context, error boundaries, `<Suspense>`, `lazy`, `use`, transitions,
+`<Profiler>`, `<StrictMode>` — all of it. react-x11 is a normal React 19
+renderer, and where React's behaviour does not depend on the DOM, it is the
+same behaviour.
+
+Everything on this page is also something you can drive by hand — in the
+apps that depend on it rather than in a panel of its own:
+
+```sh
+npm run examples:monitor      # priority: a filter over ~780 live rows
+npm run examples:chat         # <Activity>, useOptimistic, <Suspense>
+npm run examples:timer        # error boundaries, and where a crash is logged
+```
+
+Those replaced an `examples/react-features.jsx` that had a panel per feature.
+A panel proves the API exists; it cannot show you the choice, because nothing
+in it costs anything. `monitor`'s field is expensive because a process list
+is expensive, and that is the only condition under which deferring it is a
+decision rather than a demonstration.
+
+What differs is anything the DOM used to define for you:
+
+- **Paint timing.** A commit does not put pixels on screen. Frames go out on
+  a clock, so "before paint" is a real, observable boundary.
+- **Measuring.** There is no `getBoundingClientRect()` that forces layout.
+  Layout has already happened, or it has not.
+- **Hiding.** `<Suspense>` and `<Activity>` hide a `<box>` cheaply, but
+  hiding a `<window>` genuinely unmaps it, and the window manager notices.
+- **Portal containers.** There is no document to portal into.
+
+## At a glance
+
+|                                                                            |                                                                            |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `useState`, `useReducer`, `useContext`, `useMemo`, `useCallback`, `useRef` | unchanged                                                                  |
+| `useImperativeHandle`, `forwardRef`, `ref` as a prop, ref cleanup          | unchanged                                                                  |
+| `use(promise)`, `use(context)`, `React.lazy`                               | unchanged                                                                  |
+| `useOptimistic`, `useActionState`, `<Profiler>`, custom hooks              | unchanged                                                                  |
+| `useSyncExternalStore`                                                     | unchanged, and the best way to bridge non-React code                       |
+| `useTransition`, `startTransition`, `useDeferredValue`                     | work, and really do stay responsive                                        |
+| `useLayoutEffect` vs `useEffect`                                           | the difference is real — one paint versus two                              |
+| `<Suspense>`                                                               | works; read [Suspense and Activity](#suspense-and-activity) for `<window>` |
+| `<Activity>`                                                               | works; `mode="hidden"` around a `<window>` unmaps it                       |
+| Error boundaries                                                           | work — but **where you put one** decides if the window survives            |
+| `<StrictMode>`                                                             | safe to use; effects are not double-invoked on the first mount             |
+| `useId`                                                                    | works; there is very little here to use it for                             |
+| `createPortal`                                                             | use [`<popup>`](elements.md) instead — see [Portals](#portals)             |
+| `flushSync`                                                                | not exported; you almost certainly do not need it                          |
+| `useFormStatus`                                                            | not wired up                                                               |
+| React Server Components                                                    | not available                                                              |
+| anything imported from `react-dom`                                         | not available — see [Not available](#not-available)                        |
+
+## Effects, and the paint boundary
+
+Put an effect that **changes what the user sees** in `useLayoutEffect`. Put
+everything else in `useEffect`. That is the same rule as the DOM, and here
+it has a directly observable consequence:
+
+| you call `setState` from | what the user sees                                      |
+| ------------------------ | ------------------------------------------------------- |
+| `useLayoutEffect`        | one frame, with the corrected value                     |
+| `useEffect`              | one frame with the old value, then a frame with the new |
+
+So an adjustment made in `useEffect` flickers. This is not a timing race you
+can get lucky with — updates from a layout effect are folded into the frame
+being prepared, and updates from a passive effect are not.
+
+That holds for a correction computed from React state. One computed from
+**geometry** is a layout behind: a layout effect runs after the commit and
+before the layout pass, so `abs` there is still the previous frame's rect
+(zeros, on mount), and anything measured from it describes the frame
+before. For a size, let the element report it with `onLayout`
+([below](#measuring-a-node)); for a style that depends on one, write a
+container query ([styling.md](styling.md#container-queries)), which the
+pass answers in the same frame. `scrollIntoView` measures nothing when you
+call it, and neither does the part of a `scrollTo` past the extent the last
+pass measured, which is what `scrollTo(Infinity)` asks for when it follows
+rows this commit added. The pass answers both against the geometry it
+produces, so they are safe here ([elements.md](elements.md#scrolling)).
+
+The same boundary is why an event handler feels instant: react-x11 lands the
+React update caused by a click or a keystroke **before** the frame goes out,
+so the response and the default action paint together rather than a frame
+apart.
+
+```jsx
+// good — `tooTall` and `fits` are React state, so the corrected rows paint
+// in the same frame as the state that asked for them
+useLayoutEffect(() => {
+  if (tooTall) setRows(fits);
+}, [tooTall, fits]);
+```
+
+## Measuring a node
+
+**There is no forced synchronous layout.** Nothing you can call will make
+layout run so you can read the result. This is the DOM habit most likely to
+break on the way over, because in a browser `getBoundingClientRect()` both
+reads _and_ triggers.
+
+A node's `abs` rect (and `getClientRects()`) reports what the **last** layout
+produced. On the very first render of a node, that is nothing yet.
+
+What to do instead:
+
+- **Let the element tell you.** `onLayout` fires on any element after a
+  layout pass moved or resized it, with `width`/`height` (and `x`/`y`
+  within the parent) in logical pixels — once after the first layout, then
+  on change. `<box onViewport>` adds a scroller's content size, and
+  `<window onResize>` fires when the window is resized. These are the
+  supported way to react to a size.
+- **Read `abs` from a ref in a handler or a later effect**, not during the
+  render that created the node.
+- **Take a getter, not a value.** `useWindowId(ref)` and `useAnchor()` return
+  getters for exactly this reason — a value captured during render would be
+  `null` on the render where you needed it.
+
+```jsx
+const [cols, setCols] = useState(1);
+
+<box onLayout={({ width }) => setCols(Math.max(1, (width / 200) | 0))}>
+  {items.map(…)}
+</box>;
+```
+
+When what depends on the size is a _style_ rather than a decision about what
+to render, write it as a container query block instead
+([styling.md](styling.md#container-queries)): it applies in the same frame,
+where a state set from `onLayout` re-renders a frame later.
+
+If you are porting a component that measures itself and adjusts, this is the
+part to rewrite. See [elements.md](elements.md) for `onLayout`, `onViewport`
+and `onResize`, and [components.md](components.md) for `useAnchor`.
+
+## What a ref gives you
+
+Two different kinds of object, depending on the element:
+
+- **`<window>` and `<popup>`** hand back the live **window object** of
+  whichever backend is drawing — on X11 the ntk window, which is what
+  [`windowIdOf()`](elements.md) resolves to an XID. Both spell
+  `getContext('2d')` and `requestAnimationFrame` the same way; anything
+  past that is the backend's own surface, so a component that reaches
+  further should say which backend it is for.
+- **every other element** hands back its **node**: `focus()`, `blur()`,
+  `focused`, `hitTest()`, `containsPoint()`, `getClientRects()`, and `abs`
+  for its position and size. `<textinput>`/`<textarea>` additionally match
+  the DOM closely enough that libraries like react-hook-form drive them
+  through a ref.
+
+A window ref is `null` until that window exists, and refs attach after the
+commit — so read them in effects and handlers, never during render.
+
+For `<canvas>`, note that the **node is not a drawing surface**. There is no
+`getContext()` on it; you draw in `onDraw`, which the renderer calls with a
+context whenever the canvas needs repainting:
+
+```jsx
+<canvas onDraw={(ctx, { width, height }) => { …}} />
+```
+
+To make it repaint, change something React can see — a prop, state, or the
+`cacheKey`. That is the supported path, and it is usually what you want.
+There is an imperative escape hatch for element authors in
+[extending.md](extending.md), but note that it lives on the **owning
+window**, not on the drawn node, despite what the bundled types currently
+say (see [Known gaps](#known-gaps)).
+
+## Transitions, and what stays responsive
+
+`useTransition`, `startTransition` and `useDeferredValue` all work, and they
+really do keep the UI responsive — React will interrupt a transition render
+to handle an incoming click or keystroke.
+
+What is worth knowing is that **transitions are the mechanism that does
+this**. An ordinary `setState` — from a handler, a timer, a socket callback —
+renders in one uninterruptible pass, however much work it is. If a render is
+big enough to drop a frame, wrapping it in `startTransition` (or deferring
+its input with `useDeferredValue`) is not a micro-optimisation, it is the
+difference between a responsive window and a frozen one.
+
+```jsx
+const [pending, startTransition] = useTransition();
+
+// typing stays instant; the expensive list catches up
+const onChange = (e) => {
+  setQuery(e.value);
+  startTransition(() => setResults(search(e.value)));
+};
+```
+
+Two smaller notes:
+
+- `root.render()` is **synchronous** — the tree is committed before the call
+  returns. Wrapping it in `startTransition` does nothing.
+- A `startTransition` inside a click handler is still a transition. It does
+  not inherit the handler's urgency.
+
+react-x11 already classifies X11 input for you: presses, releases, keys,
+focus changes, window close and drops are urgent; pointer motion and
+drag-over are not, which is what keeps a motion burst from flooding the
+renderer. You do not have to do anything to get this.
+
+[`examples/monitor.jsx`](../examples/monitor.jsx) is this paragraph with a
+keyboard on it: a filter over hundreds of live rows, where one keystroke
+changes every row on screen. Without the deferral the caret waits for the
+table; with it the field stays under the fingers and the rows arrive a beat
+later. Two things there are worth copying, and both are one-line mistakes in
+the other direction: the expensive subtree is
+`memo`ised (or the urgent render rebuilds it anyway, and deferring buys
+nothing), and no prop that changes on every update — not even a "stale"
+border — is passed into it.
+
+### Bridging non-React code
+
+`useSyncExternalStore` is the right tool for anything that lives outside
+React — a timer, a D-Bus signal, a socket, an ntk event. It is also faster
+here than a hand-rolled `setState` bridge: a store notification is applied
+urgently and lands in the next microtask, where the equivalent `setState`
+waits a turn longer.
+
+Every mainstream store (zustand, jotai, valtio, redux, XState) works with no
+adapter for this reason. The [window-manager
+example](../examples/wm.jsx) is the worked case: the WM core is a plain
+store, and the UI subscribes to it.
+
+## Suspense and Activity
+
+`<Suspense>` works. The one thing to plan for is layout: a hidden subtree
+gives up its space entirely, so the fallback lays out as if the real content
+were not there. **Size your fallback deliberately**, or the window collapses
+to the fallback and jumps back on reveal.
+
+```jsx
+<Suspense fallback={<box style={{ height: 240 }} />}>
+  <Report />
+</Suspense>
+```
+
+**Focus goes with the hidden tree and comes back with it.** A field inside
+the boundary gives up the keyboard when the fallback appears — nothing
+invisible collects keystrokes — and gets it back on the reveal unless
+something else took focus meanwhile, so a boundary that re-suspends
+mid-edit does not drop the user out of what they were typing. See
+[events.md](events.md#focus-and-visibility) for the rules and the way out.
+
+**Scroll positions come back too.** What a hidden boundary holds is not
+placed while it is hidden — the same as under `display: 'none'` — so a scroll
+pane in it is not clamped to the start of content it no longer lays out,
+reports no `onViewport` or `onScroll` until it is shown, and is shown at the
+offset it was left at. A tab kept mounted under `<Activity>` reopens on the
+row the user was reading.
+
+If a `<window>` is inside the boundary, hiding it **unmaps the real window**.
+The window manager treats the reveal as a new window: it may re-place it,
+restack it, or apply its own geometry, and anything the user did to it can be
+lost. Prefer suspending _inside_ a window over suspending the window itself.
+
+`React.lazy` works. If you ship a single-file bundle, note that dynamic
+`import()` gets inlined — you keep lazy _evaluation_ but get no code
+splitting; see [packaging.md](packaging.md).
+
+`<Activity>` works, and `mode="hidden"` around a toplevel `<window>` reads
+the same way `<Suspense>` does: the window is unmapped, and one mounted
+hidden is never mapped at all — it is created, laid out and kept, but the
+window manager only ever hears about it on the reveal. The same caveat
+applies: what the user did to the window before it was hidden is the window
+manager's to remember, and it may not.
+
+**Testing Suspense**: a promise that settles outside `act()` is not always
+picked up by an `await act()`, because React throttles the commit when a
+fallback was shown very recently. Use `waitFor` from `react-x11/test` —
+see [testing.md](testing.md).
+
+## Portals
+
+**Use `<popup>`.** It is what you want in almost every case where the DOM
+would reach for `createPortal`: a `<popup>` is written as an ordinary child
+in your JSX — so it sees context, state and props exactly where you wrote it
+— but it is a real top-level X window, so it escapes its parent's clipping
+and can extend past the window edge.
+
+```jsx
+<box>
+  <Button onClick={(e) => setAt({ x: e.screenX, y: e.screenY })}>
+    Options…
+  </Button>
+  {at && (
+    <popup
+      x={at.x}
+      y={at.y}
+      width={180}
+      height={120}
+      grab
+      onDismiss={() => setAt(null)}
+    >
+      <Menu />
+    </popup>
+  )}
+</box>
+```
+
+Its position in the JSX has no effect on where it appears — you place it in
+screen coordinates, and `useAnchor()` does that math for you when you are
+anchoring to another node.
+
+`Dialog`, `Tooltip`, `ContextMenu`, `MenuBar` and `Select` are all built this
+way — see [components.md](components.md).
+
+There is no `createPortal` export. The reconciler's own is reachable through
+the `Renderer` escape hatch, but it is not a supported surface: the container
+has to be an X connection or an X window rather than a node, and only
+`<window>`/`<popup>` can be the portal's immediate child. If you find
+yourself wanting it, you almost certainly want a second `<window>` or a
+`<popup>`.
+
+## Where to put an error boundary
+
+Boundaries work exactly as documented. The X11-specific decision is
+**placement**, and it decides whether the user's window survives:
+
+```jsx
+// good — the window and everything the WM knows about it survives
+<window title="Editor">
+  <ErrorBoundary fallback={<text>Something broke</text>}>
+    <Document />
+  </ErrorBoundary>
+</window>
+
+// the window itself is destroyed and recreated on a throw
+<ErrorBoundary fallback={<window title="Editor">…</window>}>
+  <window title="Editor">
+    <Document />
+  </window>
+</ErrorBoundary>
+```
+
+A recreated window is a **new** window: its position, size, stacking,
+maximized state and anything else the user or the window manager did to it
+are gone. Put the boundary inside the window unless you genuinely want the
+window replaced.
+
+An **uncaught** error unmounts the whole tree, which here means every window
+disappears while the process stays alive. `createRoot` takes
+`onUncaughtError`, `onCaughtError` and `onRecoverableError` so you can decide
+what that should mean for your app — the default logs and sets a failing exit
+code. See [events.md](events.md).
+
+One thing React does not cover: **a throw inside an event handler never
+reaches a boundary.** (That is true in React DOM too.) react-x11 routes those
+to `onUncaughtError` instead, so they are at least reportable rather than
+silent.
+
+## Smaller notes
+
+**`useId`** works, but there is little use for it: no element takes an `id`,
+there is no hydration, and labels are associated structurally (`<Checkbox
+label>`, `<Radio>children</Radio>`). If you want a window's real identity,
+that is `useWindowId()`. Avoid putting an `id` prop on `<window>` — unknown
+props there are forwarded to the underlying window as creation attributes.
+
+**`<StrictMode>`** is safe. A discarded render costs no X11 traffic, so
+double-rendering never produces double windows. Be aware that effects are
+**not** double-invoked on the initial mount, so it will not catch a missing
+cleanup at mount the way it does in React DOM.
+
+**`memo` / `useMemo`** save CPU, not bandwidth. Rebuilding a `style` object
+or array every render is free — styles are compared by value, so an
+identical style produces no layout work, no repaint and no frame. Passing
+`style={[base, active && on]}` inline is the documented idiom, not a leak.
+See [styling.md](styling.md).
+
+**Keys** matter more for `<window>` children than for drawn ones. Reordering
+`<box>` children is cheap. Reordering sibling `<window>`s restacks real
+windows, and a missing key destroys and recreates them — with the same loss
+of window-manager state described above. To keep a window on top, use
+`alwaysOnTop` rather than ordering.
+
+**DevTools** works — set `REACT_X11_DEVTOOLS=1` and the component tree,
+props and highlight-on-hover all behave normally, with the highlight drawn
+into the real window. The Profiler **Timeline** tab is unavailable; the
+commit list and flamegraph work. See [devtools.md](devtools.md).
+
+**Fast Refresh** works without a bundler: `npx react-x11 dev app.jsx` runs
+a file with its default export mounted and every save applied in place, over
+the `react-x11/refresh` entry point, which a tool that hosts the loader
+itself registers with `--import`. Keep anything
+whose identity must survive a reload — contexts, stores — in a module you
+are not editing. See [dev tooling](ecosystem/dev-tooling.md#react-refresh)
+and the [hot-reload example](../examples/tasks.jsx), which is
+`npm run examples:tasks:hot`.
+
+## Not available
+
+**`react-dom`.** It is not a dependency, so `ReactDOM.createPortal`,
+`flushSync`, `findDOMNode`, `hydrateRoot` and `unstable_batchedUpdates` are
+not part of react-x11.
+
+The trap is not the import error — it is that `react-dom` is a required peer
+of some libraries, so it can end up installed anyway. Then the import
+resolves, and `flushSync()` runs your callback **without flushing anything**,
+because it is talking to a renderer you are not using. If a library depends
+on synchronous flushing, check `npm ls react-dom`. The
+[ecosystem register](ecosystem.md) records which packages hit this.
+
+**Server Components** are not available: there is no Flight client wired up.
+
+**`useFormStatus`** is not wired up. `useOptimistic` and `useActionState` are
+unaffected and work normally.
+
+## Known gaps
+
+Open bugs where a React feature does not yet mean here what it should:
+
+- A `<popup>` written inside a subtree that `<Suspense>` or `<Activity>`
+  hides stays on screen: React hides the topmost host instance of the branch
+  and the popup is its own X window below it, so nothing unmaps it. Focus
+  follows what is actually visible, so the popup keeps the keyboard — but
+  the popup itself has to be conditional in your JSX rather than left to the
+  boundary.
+- The bundled types declare `invalidate()` on every node; at runtime only the
+  owning `<window>` has it. Reach it as `ref.current.root` — or better, drive
+  repaints through props and `cacheKey`.