react-x11 2.51.1 → 2.53.0

package/docs/windows-integrations.md

@@ -0,0 +1,177 @@
+# Desktop integration on Windows: what works, and what does not
+
+What an app on the [win32 backend](windows.md) can reach today, what it
+cannot, and which of the gaps have a route. Every row was measured on this
+backend rather than inferred from the API's existence: "works" means a test
+asserts it or it was driven and seen.
+
+## Works
+
+| what                     | the API                                                       | how                                                                                            |
+| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| a window, composed       | `<window>`                                                    | DirectComposition surface per window, Direct2D verbs                                           |
+| text and layout          | `<text>`, `app.fonts`                                         | DirectWrite: layout, line metrics, hit testing, carets                                         |
+| glyph runs               | `ctx.drawGlyphs`, `face.glyphIdFor`/`advanceOf`               | `DrawGlyphRun` — what `<Terminal backend="vt">` positions its grid with                        |
+| variable font axes       | `style.variations`                                            | `IDWriteTextLayout4::SetFontAxisValues`                                                        |
+| app-supplied fonts       | `loadFont`, `openFont`                                        | a DirectWrite font set of the app's own, with the file's axes kept                             |
+| OpenGL                   | `<glarea>`                                                    | WGL, and `WGL_NV_DX_interop2` to reach the composed surface                                    |
+| keyboard                 | `onKeyDown`, focus                                            | `ToUnicodeEx` without consuming dead keys; X keysym vocabulary                                 |
+| pointer                  | `onMouseDown`, wheel, capture                                 | all five buttons, `SetCapture` for drags leaving the window                                    |
+| focus                    | `onFocus`/`onBlur`                                            | `WM_ACTIVATE`                                                                                  |
+| window states            | `useWindowState`, `<window maximized fullscreen alwaysOnTop>` | `ShowWindow`, `SetWindowPos`, a remembered frame for fullscreen                                |
+| screens and DPI          | `useScreens`, `useScale`                                      | per-monitor v2; no live per-window re-scale yet ([windows.md](windows.md#scale-and-dpi))       |
+| light/dark and accent    | `useSystemAppearance`                                         | `UISettings` and the theme registry; the frame follows through `DWMWA_USE_IMMERSIVE_DARK_MODE` |
+| native control bezels    | `<button>`, `<checkbox>`…                                     | the visual styles engine, on a light desktop; dark ones are drawn (Windows' are not public)    |
+| file dialogs             | `useFileDialog`                                               | the Common Item Dialog, parented, modal on the UI thread                                       |
+| clipboard                | `useClipboard`                                                | text only, and format enumeration                                                              |
+| tray icon and menu       | `useTray`                                                     | `Shell_NotifyIcon`                                                                             |
+| taskbar progress         | `useProgress`                                                 | `ITaskbarList3::SetProgressValue`                                                              |
+| a badge on the icon      | `useBadge`, `setBadge`                                        | the count drawn into an overlay icon — Windows has no badge API                                |
+| demanding attention      | `setUrgent`                                                   | `FlashWindowEx`                                                                                |
+| global hotkeys           | `useAccelerator`                                              | `RegisterHotKey`                                                                               |
+| notifications            | `notify`, `useNotifier`                                       | a tray balloon, which the shell shows as a toast                                               |
+| idle time                | `useIdle`                                                     | `GetLastInputInfo`, polled on the same adaptive wait the X rung uses                           |
+| keeping the screen awake | `keepAwake`, `useKeepAwake`                                   | `SetThreadExecutionState`, counted                                                             |
+| reading a window back    | `window.snapshot()`                                           | `PrintWindow` with `PW_CLIENTONLY` and `PW_RENDERFULLCONTENT`                                  |
+| locale                   | `systemLocale`, `useLocale`                                   | ICU's own resolution, which reads the OS on Windows — no backend code                          |
+| drag and drop            | `useDropTarget`, `useDragSource`                              | `IDropTarget` and `DoDragDrop` over OLE, both directions                                       |
+| a thumbnail toolbar      | `useThumbnailToolbar`                                         | `ITaskbarList3::ThumbBarAddButtons` — **Windows only**                                         |
+| a jump list              | `useJumpList`                                                 | `ICustomDestinationList` — **Windows only**                                                    |
+| recent documents         | `useRecentDocument`                                           | `SHAddToRecentDocs` — **Windows only**                                                         |
+| input methods            | `onCompositionStart`/`Update`/`End`, `<textinput>`            | IMM32: the preedit is drawn in the field, the candidate list follows the caret                 |
+| screen readers           | `role`, `aria-*`, `announce()`                                | a UI Automation provider over a pushed mirror of the tree                                      |
+| window identity          | `<window appId>`                                              | the AppUserModelID on the window's property store — taskbar grouping, pinning, the jump list   |
+
+## Built, with limits worth knowing
+
+### Input methods — built on IMM32, with the gaps that layer has
+
+CJK input works, through the same composition events a Wayland text-input
+drives, so an application handles one composition and gets both. The preedit
+is drawn **in the field** rather than in a floating box, and the candidate
+list follows the caret.
+
+What it does not carry is what IMM32 itself no longer carries. Modern input
+methods — the new Microsoft Japanese and Chinese IMEs included — are TSF text
+services reaching an IMM32 window through a compatibility layer, which does
+not pass on **voice typing** (Win+H inserts nothing), the shell's
+**handwriting** panel, or **shape-writing** on the touch keyboard. A TSF text
+store would close those; it is not built. Reconversion (asking the IME to
+re-open a committed word) is not wired up either, though IMM32 carries it.
+
+### Screen readers — built, without text ranges
+
+Screen readers are served by a UI Automation provider of this project's own,
+answering from a copy of the tree the app pushes, so a screen reader is never
+paced by the app's busiest moment. Roles, names, descriptions, states,
+bounding rectangles, focus and the Invoke, Toggle, Value and RangeValue
+patterns all cross; `announce()` goes out as a UIA notification. Everything an
+app writes — `role`, `aria-label`, `aria-checked`, `aria-valuenow` — is read
+by the same code the AT-SPI bridge reads, so the two backends cannot disagree
+about what a node is.
+
+**What is missing is `ITextProvider`.** A `<textinput>` exposes its value, so
+a screen reader reads the field and hears edits, but caret-by-caret and
+word-by-word navigation _inside_ it is not there.
+
+## Not implemented
+
+Ordered by what it costs an app today.
+
+### `useLauncherMenu` is inert
+
+The jump list is built (`useJumpList` above) but it is **not** what
+`useLauncherMenu` means, and is deliberately not wired to it. A launcher-menu
+item carries a callback; a jump-list task starts a _new process_ with
+arguments, because the shell launches the program rather than calling into
+the running one. Mapping one onto the other would quietly change what a click
+does.
+
+### Activation — file associations, URL schemes, second launches
+
+`useAppOpen` and `useAppActivate` never fire on Windows: there are no file
+associations, no URL schemes and no single-instance handoff yet, so a second
+launch is a second process. [uri-schemes.md](uri-schemes.md) documents what
+the other platforms do.
+
+### Eyedropper — the pixel is read, the ladder has no rung
+
+The bridge reads a screen pixel (`app.screenColorAt`, `app.pointerPosition`),
+but `useEyedropper()` reports `supported: false` here until a rung draws the
+loupe over it.
+
+### Calendar — blocked, not missing
+
+`useDesktopCalendarEvents` wants the Windows appointments API, which requires
+package identity. Unpackaged, there is nothing to call, and the hook reports
+`supported: false` rather than guessing.
+
+### Permissions — nothing to ask
+
+`usePermission` has no Windows meaning for an unpackaged app: the capability
+API is for packaged apps, and everything else sits under one per-device
+switch. The answer is `'unknown'` until something is attempted, and the
+attempt's own error is the answer.
+
+### Global menu — not a Windows concept
+
+`useGlobalMenu` is a menu bar owned by the desktop. Windows has none; a
+`<MenuBar>` drawn in the window is the whole story here, and that works.
+
+### Keyboard grabs
+
+`grabKeyboard` accepts and does nothing: there is no Windows mechanism for it.
+A popup that asked for keys gets them only while it is the foreground window.
+
+`grabPointer` is a different story — see below.
+
+## Built, with limits worth knowing: `<popup grab>`
+
+Windows has no pointer grab to give — `SetCapture` sends a window the mouse
+only while a button is already down — so the dismissal is reproduced from two
+signals, and `<Select>`, `<Menu>` and any `<popup grab>` close the way they do
+everywhere else:
+
+- a press delivered to **another window of this application** — a click in
+  the owner behind the menu, in a second window, or in the menu a submenu came
+  from;
+- the application **losing activation** — a press in another application or
+  on the desktop. A popup never takes activation itself, so opening one raises
+  no blur.
+
+**The gap**: a press on the _non-client_ area of one of our own windows — a
+title bar, a resize border — is not reported, so a menu left open while the
+user drags the window behind it stays open. X11's grab covers that and this
+does not.
+
+## What Windows has that nothing else does
+
+Some Windows surfaces have no cross-platform API to fit into, so they have
+APIs of their own, and **a backend installs a method, and its presence is the
+capability**. They are reported as features of the launcher, beside the badge
+and the progress bar:
+
+```jsx
+const launcher = useDesktopCapability('launcher');
+launcher.backend; // 'taskbar' here, 'cocoa' on a Dock
+launcher.features.thumbnailToolbar; // the buttons under the hover preview
+launcher.features.tasks; // the jump list's Tasks category
+launcher.features.recentDocuments; // the shell's Recent lists
+```
+
+They live there rather than in `useSupports()` because `useSupports` answers
+for the **display** — transparency, shaders, embedding — and a taskbar button
+is not a display property; and because a boolean cannot say _which_ launcher
+answered. Every other backend answers false for the three, and the hooks do
+nothing where the method is absent. `examples/taskbar.jsx` is the shape;
+there is no `process.platform` in it.
+
+- **Thumbnail toolbars** — `useThumbnailToolbar`: up to seven buttons under
+  the taskbar thumbnail, play/pause/next for a media app.
+- **Recent documents** — `useRecentDocument`.
+- **A jump list** — `useJumpList` (see [`useLauncherMenu`](#uselaunchermenu-is-inert)).
+- **Taskbar overlay as a status light**: `setBadge` takes a label, and an app
+  that wants a dot rather than a number can pass one character.
+
+Ideas not built yet are in the
+[design notes](../design/windows-integrations.md#what-windows-has-that-nothing-else-does).

package/docs/windows.md

@@ -0,0 +1,380 @@
+# A native Windows backend
+
+The `win32` backend draws a react-x11 app into real Win32 windows: one
+DirectComposition surface per window, Direct2D for drawing, DirectWrite for
+text. It is **the default on Windows**, and it needs the `@windowkit/win32`
+native bridge; without the bridge, `'auto'` falls back to X11. The examples
+run on it, except `wm` and `xeyes`, which are X11 window-manager demos.
+
+[windows-integrations.md](windows-integrations.md) is the row-by-row status of
+what an app can reach on Windows. Why the backend is built the way it is — the
+threading model, the rendering internals, the plan and its open questions — is
+the design record: [design/windows.md](../design/windows.md).
+
+## Choosing a backend
+
+`createRoot({ backend })`, or `REACT_X11_BACKEND` without touching code:
+
+| asked                  | on Windows                                                                                                                                                                                           |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'auto'` (the default) | `'win32'` when `@windowkit/win32` loads. Otherwise X11 through `DISPLAY`, with one console warning outside production, so a WSLg or Cygwin setup keeps working                                       |
+| `'win32'`              | the bridge is required: if it cannot load, `createRoot()` rejects with an error that lists what it tried and how to install it                                                                       |
+| `'x11'`                | an X server through `DISPLAY`. Also what `'auto'` picks when you pass `display` or `stream`. Windows has no `fc-match`, so tell ntk where the fonts are with `fontSource` or `REACT_X11_FONT_SOURCE` |
+
+```jsx
+const root = await createRoot(); // win32 on Windows, x11 if the bridge is missing
+const root = await createRoot({ backend: 'win32' }); // the bridge or an error
+```
+
+Asking for `'win32'` on any other platform throws: the backend is
+Windows-only.
+
+## Installing the bridge
+
+- `@windowkit/win32` is an `optionalDependency` of react-x11 with
+  `os: ["win32"]`, so `npm install react-x11` on Windows installs it and
+  every other platform skips it. If optional dependencies were omitted,
+  install it yourself: `npm install @windowkit/win32`.
+- Prebuilds ship for **x64 and ARM64**. Building from source needs Visual
+  Studio with the "Desktop development with C++" workload.
+- It is an N-API addon, so it loads under Bun (`bun.exe`) as well as Node.
+- `REACT_X11_WIN32_PATH=<path>` loads the bridge from a path instead of the
+  installed package: a checkout, or the file shipped beside a compiled
+  executable (see [Packaging and identity](#packaging-and-identity)).
+- An older bridge degrades feature by feature rather than failing: a missing
+  verb answers "unsupported" (for example, `useWindowState()` sees `false`,
+  and a `<glarea>`'s children are not drawn).
+- Built and measured on Windows 11. Windows 10 is not a verified target.
+
+## Threads and the event loop
+
+The bridge runs every window on a UI thread of its own, and your JS stays on
+Node's main thread. Windows' modal loops — a live resize, a native menu, a
+drag (`DoDragDrop` does not return until the drop), a file dialog — run on
+that UI thread, so **JS is never frozen by one**: timers fire, sockets read,
+React commits and frames present while the user drags or a dialog is open.
+This is the main behavioural difference from the Cocoa backend's pump mode.
+
+Events reach JS as soon as they happen, without waiting for a timer tick, and
+a handler's `setState` commits on the event that caused it.
+
+## Rendering
+
+- **Every window is composited by DWM**, so `transparent` always works and
+  `useSupports('transparency')` is always true — there is no "if a compositor
+  is running".
+- **ClearType on opaque windows, grayscale on transparent ones.** Direct2D
+  draws subpixel text only onto a surface whose alpha is ignored, so text in
+  a `<window transparent>` or `<popup transparent>` is grayscale-antialiased.
+- **Frames are paced by DWM's compositor clock**, at the refresh rate of the
+  monitor under the window; `frameRate` works as on the other backends. An
+  idle app polls nothing.
+- Only damaged rectangles are repainted, and scrolling is a blit, as on X11
+  and Cocoa.
+- **Reading pixels back**: `window.snapshot()` works once the window has
+  been composed. It rejects for a minimised or not-yet-composed window; draw
+  into an offscreen surface and read that instead.
+- `<video frames>` draws; `<video src>` does not —
+  `useSupports('mediaPlayback')` is false here.
+- Debugging: `REACT_X11_WIN32_DEBUG=1` reports every frame and what it drew
+  into, the size each paragraph is shaped at, and drag and drop;
+  `REACT_X11_WIN32_FULL_REPAINT=1` paints the whole window every frame, the
+  control for a damage bug.
+
+## Scale and DPI
+
+- Windows are **per-monitor-v2 DPI aware** whatever `node.exe`'s manifest
+  says, so nothing is bitmap-stretched and layout runs in device pixels.
+- **Fractional scale is the normal case** (125%, 150%, 175%). Layout rounds
+  to whole device pixels, so a one-logical-pixel hairline at 1.25× lands on
+  one device pixel or two depending on where it falls
+  ([scale.md](scale.md)).
+- `useScale()` is the **primary monitor's** scale when the app starts, static
+  for the life of the root as on every backend, and every window is laid out
+  at it.
+- `useScreens()` lists every monitor; its `available` is the monitor's exact
+  work area.
+- **Not yet: live per-window scale.** A window on, or dragged to, a monitor
+  at another scale is not re-laid out at that scale: it stays sharp but is
+  the wrong physical size there.
+
+## Text: DirectWrite behind the engine contract
+
+Text is DirectWrite end to end — font matching, fallback, shaping, bidi, line
+breaking, hit testing — so it looks like the platform's text, the way the
+Cocoa backend uses CoreText.
+
+- **Generic families**: `sans-serif`, `system-ui` and `ui-sans-serif` →
+  Segoe UI; `serif` → Times New Roman; `monospace` and `ui-monospace` →
+  Consolas; `cursive` → Segoe Script.
+- **Font stacks** resolve to the first family installed. A face filed under
+  another family ("Arial Black", "Segoe UI Light") is found as GDI finds it,
+  and Courier/Courier New, Times/Times New Roman and Arial/Helvetica stand in
+  for each other.
+- In laid-out text, characters the font lacks fall back to a system font,
+  as DirectWrite layouts do. `app.fonts.fallbackFor()` answers `null` (not
+  bound yet), so code drawing its own glyph runs gets no fallback face.
+- `loadFont` and `openFont` load the app's own fonts, variable axes kept;
+  `style.variations` sets axes.
+- Measurements are rounded up to whole device pixels, and lines break at the
+  same opportunities as on Cocoa, but metrics are DirectWrite's: expect a
+  pixel or so of difference from the X11 backend's layouts.
+
+## Input
+
+### Pointer
+
+- All five mouse buttons and the wheel. A drag that leaves the window keeps
+  receiving motion while a button is held.
+- A precision touchpad sends fractions of a notch; those arrive as wheel
+  events with `smooth: true`.
+- Motion and wheel are coalesced to one per frame, as on X11.
+- Not yet: pen- and touch-specific events, touchpad inertia, pinch.
+
+### Keyboard
+
+- Key events carry the same X keysym vocabulary, `codepoint` and `key` as on
+  every backend; the editing, navigation, function and keypad keys have their
+  X keysyms.
+- Dead keys compose in the layout, as the layout defines them; the backend
+  never consumes the dead-key state behind your back.
+- Tab and Return never insert a control character into a field.
+
+### IME
+
+Input methods work, through IMM32 — Chinese, Japanese and Korean composition
+reach the same `onCompositionStart`/`Update`/`End` events a Wayland
+text-input drives, so one handler serves both.
+
+- The **preedit is drawn in the field**, laid out and styled with the rest of
+  the text; Windows' floating composition window is suppressed. The
+  **candidate list** is the input method's own and follows the caret.
+- A commit arrives before the next preedit, and the active clause is the
+  preedit cursor (`cursorBegin`/`cursorEnd`), as on Wayland.
+- A `sensitive` field is not offered to the input method at all, so its text
+  never reaches a word history — as Windows does for its own password boxes.
+- **What IMM32 does not carry**: modern input methods are TSF text services
+  reaching IMM32 windows through a compatibility layer, and that layer drops
+  **voice typing** (Win+H inserts nothing), the shell's **handwriting**
+  panel and **shape-writing** on the touch keyboard. A TSF text store, which
+  would close those, is not built. Reconversion is not wired up either.
+- `REACT_X11_TRACE_IME=1` prints a line per input-method event.
+
+## Windowing semantics: what maps, what bends, what breaks
+
+**Maps**:
+
+- `title`, `width`, `height`, `x`, `y` and the natural size. `x`/`y` are
+  virtual-screen coordinates, negative left of and above the primary monitor.
+- `minWidth`/`minHeight`/`maxWidth`/`maxHeight` and `resizable` become the
+  window's size limits.
+- `fullscreen`, `alwaysOnTop`, maximise and minimise use Windows' own calls;
+  full screen is a borderless monitor-sized window that remembers the frame
+  it came from.
+- `transparent` — always available ([Rendering](#rendering)).
+- `appId` — the window's AppUserModelID
+  ([Packaging and identity](#packaging-and-identity)).
+- `<popup>` — no taskbar button, never takes activation, placed against the
+  monitor's work area as everywhere.
+- Drag and drop, both directions: `dropAccept`, `onDrag*` and `dragData`
+  hold, and JS keeps running through the drag. Windows itself refuses a drop
+  from Explorer into an elevated app.
+
+**Bends**:
+
+- `<popup grab>`: there is no pointer grab on Windows, so a press in another
+  of the app's windows, or the app losing activation, closes the popup
+  instead. The gap: a press on one of the app's own title bars or resize
+  borders does not, so a menu stays open while its window is dragged.
+- `states`: `shaded` and `sticky` have no Windows call and resolve false,
+  which `useWindowState()` reports. `focused` can be refused by Windows'
+  foreground rules, and then simply does not change.
+- `embeddable` and `<foreign>`: see
+  [Embedding](#embedding-frame-foreign-window-embeddable).
+- The global menu: Windows has none; draw a `<MenuBar>`.
+
+**Inert** — accepted and ignored, so shared code stays branch-free:
+
+- `decorations={false}`, today. A titlebar drawn in the window and moved
+  from `onMouseMove` loses snapping and the Snap Layouts flyout.
+- `transientFor`, `windowType`.
+- `grabKeyboard`: a popup gets keys only while it is the foreground window.
+- `onClientMessage` never fires; there is no X.
+
+**Breaks**, by design: window managers (`examples/wm.jsx`) — DWM owns every
+frame — and `ssh -X` remoting, for which the X11 backend stays the answer
+([remote.md](remote.md)).
+
+## The desktop around the app
+
+No D-Bus or portals here: each service has a Windows rung or an honest
+floor. [windows-integrations.md](windows-integrations.md) has the measured
+status of each; in short:
+
+- **Work**: `useFileDialog()` (Windows' own dialog, owned by the window that
+  asked), `useSystemAppearance()` (light/dark, accent, high contrast, reduced
+  motion; the window frame follows dark mode), `useTray()`, `useProgress()`,
+  `useBadge()`/`setBadge()` (drawn into the taskbar's overlay icon — pass one
+  character for a dot), `setUrgent()`, `useIdle()`, `keepAwake()`,
+  `useLocale()`.
+- **Global shortcuts** (`useAccelerator()`): system-wide, no admin. A chord
+  another app holds fails; Windows-key chords are reserved.
+- **Notifications** (`notify()`, `useNotifier()`) are tray balloons, which
+  the shell shows as toasts and keeps in the Action Center: plain text with a
+  severity — no actions, click events, updates or custom icon, as the
+  capabilities say.
+- **Clipboard** (`useClipboard()`): text only — writing anything else
+  rejects. No `PRIMARY`. `watch()` notices a change within about 400 ms.
+- **Windows only**: `useJumpList()`, `useThumbnailToolbar()`,
+  `useRecentDocument()`, reported as features of
+  `useDesktopCapability('launcher')`.
+- **Answer "no"**: `useLauncherMenu()` is inert (a jump-list task starts a new
+  process — use `useJumpList()`); `useAppOpen()` and `useAppActivate()` never
+  fire (no file associations, URL schemes or single instance yet);
+  `useEyedropper()` reports `supported: false`; `usePermission()` answers
+  `'unknown'`; `useDesktopCalendarEvents()` is `supported: false` unless the
+  app is packaged.
+- **Native control bezels** are the system's own while the desktop is light,
+  and drawn in dark mode, because Windows' dark common controls are not
+  public.
+
+## Accessibility: UI Automation
+
+Screen readers read the app through UI Automation. What an app writes —
+`role`, `aria-*`, `announce()` — is read by the same code the Linux AT-SPI
+bridge reads, so the two cannot disagree about what a node is.
+
+- **Crosses**: roles, names, descriptions, states, bounding rectangles,
+  focus and hit testing; the Invoke, Toggle, Value and RangeValue patterns;
+  `announce()` as a UIA notification.
+- The bridge answers from a copy of the tree the app pushes after commits, so
+  a screen reader never waits on a busy JS thread. Pushes are paced as
+  [accessibility.md](accessibility.md#how-often-the-bridge-speaks) describes.
+- **Missing: text ranges.** A `<textinput>` exposes its value, so a screen
+  reader reads the field and hears edits, but cannot move caret by caret or
+  word by word inside it.
+- `REACT_X11_TRACE_A11Y=1` prints a line per push and action.
+
+## 3D: `<glarea>`
+
+`<glarea>` draws through OpenGL on the **GPU vendor's driver**, and its frames
+are composited with the rest of the window, the window's alpha included.
+
+- The context is an OpenGL ES-profile one: GLSL ES shaders, and the
+  WebGL 2-shaped `gl` (`gl.bindBuffer`, …) of the X11 direct backend.
+  `@react-x11/components/three` runs on it. No `glPolicy` is needed: this
+  backend is always direct.
+- It needs the driver's `WGL_NV_DX_interop2`, which NVIDIA and AMD drivers
+  have and some Intel configurations lack.
+- **Without a vendor driver** — a virtual machine without GPU passthrough, a
+  CI runner, a fresh install before Windows Update fetched the driver, some
+  Remote Desktop sessions — Windows offers only the OpenGL 1.1 software
+  rasterizer, which has no shaders. `<glarea>` then reports one `onError`
+  naming the reason, and `useSupports('shaders')` is false. The ANGLE
+  fallback that would cover these machines is not built.
+- `useSupports('shaders')` is false for one tick and then true: the GL probe
+  (about 120 ms) runs the first time something asks, not at startup.
+- A `<glarea>`'s children are drawn on composited panes above the surface,
+  translucency included (`useSupports('glOverlay')` is true). The surface
+  takes no pointer input; the pointer reaches the tree.
+
+Background: [design/windows-gl.md](../design/windows-gl.md).
+
+## Embedding: `<Frame>`, `<foreign>`, `<window embeddable>`
+
+The API is the same as everywhere; what answers it differs.
+
+- **`<Frame src>` works.** The pane runs in its own process and draws into a
+  composition surface the host shows; `props`, `fallback` and `restart()`
+  behave as on every backend ([frame.md](frame.md)). The host is the pane's
+  parent process; a pane started some other way names it with
+  `createRoot({ win32: { paneHostPid } })`.
+- **`<foreign>` refuses.** Windows' cross-process child windows attach the two
+  programs' input queues, so a hung guest would hang the host.
+  `useSupports('embedding')` is false, and a `<foreign>` reports one
+  `onError`:
+
+  ```
+  react-x11: <foreign> needs a backend with cross-process window embedding,
+  and this one has none — so nothing can be put in it. Ask
+  useSupports('embedding') before rendering one.
+  ```
+
+  ```jsx
+  const embedding = useSupports('embedding');
+  return embedding ? <foreign onReady={spawnInto} /> : <text>X11 only</text>;
+  ```
+
+- **`<window embeddable>`** is created and not shown, as everywhere.
+  `windowHandleOf(ref)` / `useWindowHandle(ref)` returns a **composition
+  surface handle** already valid in the host process — not an HWND, because a
+  composition target stops presenting once its window is made a child. Pass
+  it to the host out of band, as an XID is passed on X11. The host must bind
+  a composition surface to a visual of its own (another react-x11 app, WinUI
+  3, a DirectComposition-based host); a plain Win32 or OLE document host
+  cannot. The host is the parent process unless
+  `createRoot({ win32: { paneHostPid } })` names another.
+- OLE embedding (a pane inside a Word document) is not supported.
+
+Background: [design/windows-embedding.md](../design/windows-embedding.md).
+
+## Packaging and identity
+
+- **`node app.js` works**, with two cosmetic problems. `node.exe` is a
+  console program, so launched from a shortcut it opens a console window.
+  And without an `appId`, the taskbar groups the app's windows with every
+  other `node.exe` window under Node's icon, and pinning pins `node.exe`.
+- **`<window appId>`** (or the class half of `wmClass`) sets the window's
+  AppUserModelID, per window, before it is shown. The taskbar groups by it,
+  pinning pins it, and the jump list belongs to it. A pinned tile relaunches
+  the command line that started the process, named after the window's title,
+  with the executable's icon.
+- **A single executable** ([packaging.md](packaging.md) tier 3,
+  `node --build-sea`) is a copy of `node.exe` with the app inside. After the
+  build: a manifest of the app's own with `rcedit`, the GUI subsystem with
+  `editbin /SUBSYSTEM:WINDOWS` so no console opens, then the signature.
+  Windows 11 24H2 also has a manifest setting that detaches the console when
+  launched from Explorer and keeps it in a terminal. Ship the bridge beside
+  the executable and name it with `REACT_X11_WIN32_PATH`.
+- **`bun build --compile`** has `--windows-hide-console` and icon and
+  metadata flags, but no way to supply a manifest; `bun.exe`'s own manifest
+  has no compatibility section, and what that changes for DPI and DWM is not
+  yet verified.
+- **Distribution**: Authenticode signing, which SmartScreen's reputation
+  follows. MSIX package identity is what unlocks the calendar, the
+  capability-status API and declared protocol activation.
+- [packaging.md](packaging.md) has no Windows tier yet.
+
+## Testing
+
+- `react-x11/test` runs a tree against an in-process X server or the mock,
+  on Windows as anywhere ([testing.md](testing.md)) — it exercises the X11
+  backend, not this one.
+- `window.snapshot()` reads a composed window back on a real Windows desktop
+  (above).
+- Test at **fractional scales** — 1.25 and 1.5, not only 1 and 2. Logical and
+  device pixels part company there, and a test at scale 1 cannot tell which
+  of the two a coordinate is in.
+- GitHub-hosted Windows runners have an interactive desktop (1024×768) and no
+  GPU driver, so `<glarea>` reports its error there; the rest of the backend
+  on Direct3D's software device (WARP) is not yet verified on them.
+
+## Not supported yet
+
+- Live per-window scale: a window on a monitor at another scale is not
+  re-laid out ([Scale and DPI](#scale-and-dpi)).
+- UI Automation text ranges: no caret or word navigation inside a field.
+- TSF: voice typing, handwriting and shape-writing; IME reconversion.
+- `decorations={false}`, `transientFor`, and a drag-region API for drawn
+  titlebars (snapping, Snap Layouts).
+- Clipboard formats other than text: images, HTML, file lists.
+- File associations, URL schemes, single instance (`useAppOpen`,
+  `useAppActivate`); `useLauncherMenu`.
+- Toasts with actions or click events (notifications are balloons).
+- `useEyedropper()`; the calendar without package identity.
+- `<glarea>` without a vendor OpenGL driver (ANGLE).
+- `<video src>`.
+- Compositor-side animation: transitions run on the frame clock, so a long
+  JS block stalls them, unlike on Cocoa.
+- Pen- and touch-specific input, touchpad inertia and pinch.
+- `<foreign>`, OLE embedding, window managers and `ssh -X` — by design.

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "react-x11",
-  "version": "2.51.1",
+  "version": "2.53.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "bin": {
     "react-x11": "./src/cli/index.js"
   },
   "files": [
-    "src"
+    "src",
+    "!src/cli/create-react-x11",
+    "docs/*.md",
+    "docs/*/*.md"
   ],
   "scripts": {
     "test": "node --import tsx --test --test-timeout=60000",
@@ -69,6 +72,7 @@
     "labs:direct-gl": "tsx examples/labs/direct-gl.jsx",
     "labs:gl-overlay": "tsx examples/labs/gl-overlay.jsx",
     "examples:viewer3d": "tsx examples/viewer3d.jsx",
+    "examples:video": "tsx examples/video.jsx",
     "examples:transparent": "tsx examples/transparent.jsx",
     "examples:windows": "tsx examples/windows.jsx",
     "examples:wm": "tsx examples/wm.jsx",
@@ -107,7 +111,7 @@
     "ical.js": "^2.2.1",
     "image-in-browser": "^3.6.0",
     "linebreak": "^1.1.0",
-    "ntk": "^8.23.2",
+    "ntk": "^8.24.0",
     "react-reconciler": "^0.34.0",
     "yoga-layout": "^3.2.1"
   },
@@ -228,6 +232,10 @@
     "./frame/child": {
       "types": "./src/frame/child.d.ts",
       "default": "./src/frame/child.js"
+    },
+    "./create": {
+      "types": "./src/cli/create.d.ts",
+      "default": "./src/cli/create.js"
     }
   },
   "types": "./src/index.d.ts"

package/src/Reconciler.js

@@ -678,7 +678,7 @@ const isNtkApp = (v) =>
  *
  * `'auto'` — the default — is one rule: macOS gets the native Core
  * Animation backend, everything else gets X11 via `$DISPLAY`. (More rungs —
- * Wayland — join this ladder, not a new one; docs/wayland.md.) On a mac
+ * Wayland — join this ladder, not a new one; design/wayland.md.) On a mac
  * without the `@windowkit/appkit` bridge installed, auto falls back to X11 so
  * an XQuartz setup keeps working; asking for `'cocoa'` by name means the
  * bridge is required, and its absence is an error that says how to fix it.
@@ -809,7 +809,7 @@ export async function createRoot(options = {}) {
   // The cocoa backend's desktop is not freedesktop's: the AT-SPI bridge and
   // the D-Bus global menu have nothing to register against there, so they
   // default off (their macOS replacements are their own workstream —
-  // docs/macos.md). The appearance ladder stays on: its macOS rung is the
+  // design/macos.md). The appearance ladder stays on: its macOS rung is the
   // one that answers. An explicit `desktop` option still wins.
   setDesktopIntegration(
     rest.desktop ??

package/src/a11y.js

@@ -1289,7 +1289,7 @@ export function startA11y(app) {
   // presence *is* the capability — the same rule the rest of the library
   // uses. The Windows backend installs one, because UI Automation asks
   // synchronously and has to be answered from a pushed copy rather than from
-  // the live tree (docs/windows.md §Accessibility); AT-SPI's asynchronous
+  // the live tree (design/windows.md §Accessibility); AT-SPI's asynchronous
   // questions are answered from the tree itself, below.
   if (typeof app?.startAccessibility === 'function') {
     startPromise = Promise.resolve()

package/src/backend/context2d.js

@@ -1,7 +1,7 @@
 // A canvas-shaped 2d context over a **verb table** — the drawing dialect
 // every native backend answers, and the one place it is written down.
 //
-// This is macos.md §"The split" step 4, taken when a second native backend
+// This is design/macos.md §"The split" step 4, taken when a second native backend
 // started: the class takes its `native` as a constructor argument and calls
 // nothing else, so one wrapper drives @windowkit/appkit's CoreGraphics verbs
 // and @windowkit/win32's Direct2D verbs alike. A bridge that lacks an
@@ -16,7 +16,7 @@
 //
 // On the surface presenter this is the whole drawing path; on the layer
 // presenter it stays as the fallback every painted-code node (<canvas>,
-// <svg>, registered elements) rasters through — docs/macos.md §"Custom
+// <svg>, registered elements) rasters through — design/macos.md §"Custom
 // drawing on a layer tree".
 //
 // The native surface holds the real graphics state (paths, CTM, clip); this
@@ -322,7 +322,7 @@ const NON_RECT = Symbol('non-rectangular clip');
  * linear in it: 14ms, 29ms, 56ms, 113ms. The driver is the subpath count,
  * not the vertex count — one 26,000-vertex subpath strokes in 4ms where
  * two thousand 13-vertex ones take 208. The full table, the two shapes
- * left whole and why, are in docs/macos.md
+ * left whole and why, are in design/macos.md
  * §"Stroking a path with many subpaths".
  *
  * Note the X11 context wants the opposite — there a stroke is an a8