react-x11 2.51.1 → 2.53.0

package/docs/permissions.md

@@ -0,0 +1,143 @@
+# 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
+
+Like the [file dialog](filedialog.md)'s, chosen for you — 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 per-device portals,
+`org.freedesktop.portal.Camera`, `.Location`, …, are not wired up). 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 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.
+
+Design notes: [design/permissions.md](../design/permissions.md).

package/docs/react-features.md

@@ -0,0 +1,405 @@
+# React features
+
+**Everything in React core behaves as documented** — hooks, context, error
+boundaries, `<Suspense>`, `lazy`, `use`, transitions, `<Profiler>`,
+`<StrictMode>`. react-x11 is a normal React 19 renderer, and where React's
+behaviour does not depend on the DOM, it is the same behaviour. This page is
+the caveats, and the four places where a DOM habit quietly does not work.
+
+The examples that exercise it:
+
+```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
+```
+
+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`, `useRef`                  | unchanged                                                         |
+| `useMemo`, `useCallback`, custom hooks                            | unchanged                                                         |
+| `useImperativeHandle`, `forwardRef`, `ref` as a prop, ref cleanup | unchanged                                                         |
+| `use(promise)`, `use(context)`, `React.lazy`                      | unchanged                                                         |
+| `useOptimistic`, `useActionState`, `<Profiler>`                   | 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; [around a `<window>`](#suspense-and-activity) it unmaps it |
+| `<Activity>`                                                      | works; `mode="hidden"` around a `<window>` unmaps it              |
+| Error boundaries                                                  | work — but **where you put one** decides if the window survives   |
+| `<StrictMode>`                                                    | safe; 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, every time: 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). 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` and `scrollTo` — including
+`scrollTo(Infinity)` to follow rows this commit added — are safe here: the
+pass answers them against the geometry it produces
+([elements.md](elements.md#scrolling)).
+
+The same boundary is why an event handler feels instant: the React update
+caused by a click or a keystroke lands **before** the frame goes out, so the
+response and the default action paint together.
+
+```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, as `getBoundingClientRect()` does in a
+browser.
+
+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.
+
+**Transitions are the only 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, `startTransition` (or `useDeferredValue` on its input) 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.
+
+Input is already classified for you: presses, releases, keys, focus
+changes, window close and drops are urgent; pointer motion and drag-over are
+not, which keeps a motion burst from flooding the renderer.
+
+[`examples/monitor.jsx`](../examples/monitor.jsx) is the worked case: a
+filter over hundreds of live rows, where one keystroke changes every row on
+screen. Two things there are worth copying: 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 — and faster than a
+hand-rolled `setState` bridge: a store notification is applied urgently, in
+the next microtask, where the equivalent `setState` waits a turn longer.
+Every mainstream store (zustand, jotai, valtio, redux, XState) works with no
+adapter. 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. Plan for layout: a hidden subtree gives up its space
+entirely, so **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.** A hidden boundary's content is not laid
+out while hidden (as under `display: 'none'`), so a scroll pane in it is not
+clamped, reports no `onViewport` or `onScroll` until shown, and reappears at
+the offset it was left at — a tab kept 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>` unmaps
+it the same way; one mounted hidden is created and laid out but never
+mapped until 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>`** where the DOM would reach for `createPortal`. A `<popup>`
+is an ordinary child in your JSX — it sees context, state and props where
+you wrote it — but a real top-level 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 decision specific to a desktop
+renderer 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: `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 talks 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`.