react-x11 2.52.0 → 2.53.0

package/docs/windows-integrations.md

@@ -1,11 +1,9 @@
 # Desktop integration on Windows: what works, and what does not
 
-[windows.md](windows.md) is the design: what the backend is for and how it is
-built. This is the status — what an app running on `@windowkit/win32` can
-actually reach today, what it cannot, and which of the gaps have a route.
-
-Everything below 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.
+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
 
@@ -21,11 +19,11 @@ API's existence. "Works" means a test asserts it or it was driven and seen.
 | 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; `WM_DPICHANGED`                                                                |
+| 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, where its dark variants are real — measured, not assumed             |
+| 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 and format enumeration                                                                    |
+| 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                                |
@@ -34,7 +32,7 @@ API's existence. "Works" means a test asserts it or it was driven and seen.
 | 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                                                              | PW_RENDERFULLCONTENT` |
+| 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**                                         |
@@ -48,43 +46,33 @@ API's existence. "Works" means a test asserts it or it was driven and seen.
 
 ### Input methods — built on IMM32, with the gaps that layer has
 
-CJK input works: `WM_IME_*` reaches `src/win32/ime.js`, which drives 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. Windows has
-stopped loading IMM32 input methods, so every modern one — the new Microsoft
-Japanese and Chinese IMEs included — is a TSF text service reaching an IMM32
-window through a compatibility layer, and that layer 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 is what closes
-those; windows.md §"IME" has the design and why it is the harder rung.
+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.
 
-Reconversion (asking the IME to re-open a committed word) is not wired up
-either, though IMM32 carries it.
+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
 
-`WM_GETOBJECT` is answered by a UI Automation provider of this project's own
-(`windows/src/uia.cc`), served from a mirror `src/win32/a11y.js` pushes. 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 from `src/a11y.js`, the same pure functions the
-AT-SPI bridge reads, so the two backends cannot disagree about what a node is.
-
-The mirror is the deliberate part. UIA's calls are synchronous and frequent —
-one focus change is dozens of property reads — so answering them from the live
-tree would pace the screen reader by the app's busiest moment. windows.md
-§"Accessibility: UI Automation" has the argument; it named AccessKit as the
-reuse candidate for the same shape, and a provider of our own was built
-instead so the release pipeline does not grow a Rust toolchain for both
-architectures.
-
-**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. That is the next piece.
+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
 
@@ -94,27 +82,22 @@ Ordered by what it costs an app today.
 
 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.
-
-They become the same feature once a second launch can hand its arguments to
-the first, which is the activation work below.
+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` fire on macOS and through the freedesktop
-transport on Linux. On Windows an app has to register its associations under
-`HKCU\Software\Classes`, declare an AppUserModelID, and make the second launch
-hand its arguments to the first and exit — a named mutex and a `WM_COPYDATA`,
-or `ISingleInstanceApp`. [uri-schemes.md](uri-schemes.md) documents what the
-other platforms do.
+`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 through GDI (`app.screenColorAt`,
-`app.pointerPosition`), but `src/screencolor.js` has no rung that calls it,
-so `useEyedropper()` reports `supported: false` here until one draws the
+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
@@ -126,9 +109,9 @@ package identity. Unpackaged, there is nothing to call, and the hook reports
 ### 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 honest answer is `'unknown'` until something is attempted and the attempt's
-own error is the answer.
+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
 
@@ -137,43 +120,36 @@ own error is the answer.
 
 ### Keyboard grabs
 
-`grabKeyboard` accepts and does nothing: there is no Windows mechanism for it,
-and nothing in the tree reads its result. A popup that asked for keys gets them
-only while it is the foreground window.
+`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>`
 
-A menu closing when you click beside it is what the pointer grab is _for_, and
-Windows has no grab to give: `SetCapture` sends a window the mouse only while a
-button is already down, so a press that starts elsewhere never arrives. The
-effect is reproduced from two signals instead, and `<Select>`, `<Menu>` and any
-`<popup grab>` dismiss the way they do everywhere else:
+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
+- 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 is `WS_EX_NOACTIVATE`, so it never takes activation
-  itself and opening one raises no blur.
-
-Both end in the same made-up outside press the Wayland backend sends for
-`xdg_popup.popup_done`, and the Cocoa backend's grab rule redirects a press to
-the holder the same way, so all four backends answer a dismissal through one
-path (`_dismissOutside` in src/events.js).
+- 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. The bridge does not report those, so a menu left
-open while the user drags the window behind it stays open. X11's grab covers
-that and this does not.
+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
 
-Things with no cross-platform API to fit into. Three of them now have one of
-their own, and the rule that makes that safe is worth stating once: **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:
+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');
@@ -186,48 +162,16 @@ 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, which is the whole reason capabilities carry a `backend` and a
-feature map. Every other backend answers false for the three without knowing
-Windows exists, 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.**~~ Built: `useThumbnailToolbar`. Up to seven buttons
-  under the taskbar thumbnail — play/pause/next for a media app. The Dock has
-  nothing like it; the closest sibling is the macOS Touch Bar, which is gone.
-- **A custom taskbar thumbnail and peek.** `DWM_THUMBNAIL_PROPERTIES` and
-  `WM_DWMSENDICONICTHUMBNAIL` let an app answer the hover preview with
-  something other than a shrunken window — a document's first page, a chart.
-- **Tabbed thumbnails.** One taskbar entry per document with
-  `ITaskbarList4::SetTabProperties`, which is how browsers put tabs on the
-  taskbar.
-- ~~**Recent documents.**~~ Built: `useRecentDocument`.
-- **Explorer verbs.** "Open with", a context-menu handler, a preview handler,
-  a thumbnail provider. All of these are COM servers registered per file type,
-  and on Windows 11 a context-menu handler must be a packaged app extension —
-  which puts them behind packaging along with the calendar.
-- **Protocol activation.** `myapp://` as a first-class launch, which is the
-  activation work above seen from the other side.
-- **Taskbar overlay as a status light.** Already reachable: `setBadge` takes a
-  label, and an app that wants a dot rather than a number can pass one
-  character.
-
-## What would fit this library and exists nowhere yet
-
-Not Windows-specific — gaps in the cross-platform surface that Windows happens
-to be able to answer.
-
-- **A print dialog and a print surface.** No backend has one. Windows has
-  `PrintDlgEx` and the XPS document API; macOS has `NSPrintOperation`;
-  freedesktop has the portal. A `<Print>` surface that takes the same verb
-  table the screen does is a natural fit for a renderer that already draws
-  through one.
-- **A colour chooser.** `useEyedropper` samples a pixel; nothing offers the
-  system's colour picker. `IColorPickerDialog` (WinUI), `NSColorPanel` and the
-  portal all exist.
-- **A font chooser.** `IDWriteFontSet` plus the Common Item Dialog's
-  chooser, `NSFontPanel`, the portal's.
-- **Session lifecycle.** `WM_QUERYENDSESSION` and `WM_ENDSESSION` on Windows,
-  `NSApplicationDelegate` on macOS, the session manager on Linux — an app that
-  wants to save before logout has no hook on any backend.
-- **Power and battery.** `GetSystemPowerStatus`, `IOPowerSources`, UPower.
-  A `useBattery` would be one hook over three.
+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).