winui-svelte 0.0.5 → 0.0.7

package/API.md

@@ -18,6 +18,7 @@ monorepo needs no build step (the repository is a pnpm workspace, see
 | `winui-svelte/host` | `src/renderer/host/host.ts` | `renderer`, the renderer WinUI controls are built through (`mountControl` makes it the active one), and the mount-target plumbing below; not for app code |
 | `winui-svelte/scroll-timeline` | `src/web-apis/scroll-timeline.ts` | `installScrollTimeline()`: `ScrollTimeline`, `ViewTimeline` and `element.animate(keyframes, { timeline })` over Composition (the CSS side is `winui-svelte/css/scroll-timeline`, which a sheet that uses `animation-timeline` imports) |
 | `winui-svelte/view-transitions` | `src/web-apis/view-transitions.ts` | `installViewTransitions()`: `document.startViewTransition` and `ViewTransition` over WinUI's connected animations (the CSS side is `winui-svelte/css/view-transition`, which a sheet or style attribute that sets `view-transition-name` imports) |
+| `winui-svelte/dialogs` | `src/web-apis/dialogs.ts` | `installDialogs()`, `showDialog()`, `useDialogWindow()`, `DialogResult`, `DialogButton`: `alert`, `confirm` and `prompt` over `ContentDialog`, as promises (opt-in; see Dialogs) |
 | `winui-svelte/element-animation` | `src/renderer/host/element-animation.ts` | `enableElementAnimation()`: what Svelte's `transition:`, `in:`, `out:`, `animate:` and `svelte/motion` ask of an element, on WinUI controls (the Vite plugin calls it from a component that uses them; otherwise not bundled) |
 | `winui-svelte/attached-owners` | `src/components/attached-owners.ts` | `preloadAttachedOwners(names)`: loads the modules attached properties (`canvasLeft`, `gridRow`) are written through (the Vite plugin calls it from a component whose markup or script names one, so the property is set with the control; a prop named nowhere, built from a computed key, needs `await preloadAttachedOwners(["Canvas"])` first, or its control throws) |
 | `winui-svelte/settings` | `src/settings/index.ts` | `SettingsCard`, `SettingsExpander`: Fluent settings cards after the Community Toolkit's (opt-in) |
@@ -37,20 +38,34 @@ monorepo needs no build step (the repository is a pnpm workspace, see
 | `winui-svelte/bootstrap` | `src/window/bootstrap.ts` | `initWindowsAppSdk()`; imports nothing of WinRT, safe on the host's main thread |
 | `winui-svelte/thread` | `src/window/thread.ts` | `runOnUiThread()`; imports only dynwinrt, so the apartment comes first |
 | `winui-svelte/window` | `src/window/index.ts` | `runWindow()`, `exitApplication()`, `createWindow()`, `startTimer()`, `systemSettings()`, the picker options (see App services) |
-| `winui-svelte/app` | `src/app/index.ts` | `ensureSingleInstance()`, `notify()`, `activateInstance()`, `activateOrLaunch()`, `launchApp()`, `relaunch()`, `restartAfterCrash()` (opt-in; see App lifecycle) |
+| `winui-svelte/window/foreground` | `src/window/foreground.ts` | `trackForeground()`, `bringWindowToFront()`, `shouldRestore()` (opt-in; see Following the foreground app) |
+| `winui-svelte/app` | `src/app/index.ts` | `ensureSingleInstance()`, `notify()`, `activateInstance()`, `activateOrLaunch()`, `launchApp()`, `startTray()`, `relaunch()`, `restartAfterCrash()` (opt-in; see App lifecycle) |
+| `winui-svelte/app/shell` | `src/app/shell/index.ts` | `trash()`, `openWith()`, `createShortcut()`, `readShortcut()`, `registerAppPath()`, `ShellFailure` (opt-in; see Shell verbs) |
 | `winui-svelte/app/activation` | `src/app/activation/index.ts` | `installProtocolHandlers()`, `registerFileTypes()`, `launchAtLogin()`, `startActivation()`, `ActivationKind` (opt-in; see Activation) |
+| `winui-svelte/app/jump-list` | `src/app/jump-list/index.ts` | `setJumpListTasks()`, `clearJumpList()` (opt-in; see Jump list tasks) |
 | `winui-svelte/data-transfer` | `src/data-transfer/index.ts` | `enableDragEvents()`, `dropzone`, `draggable`, `filePicker`, `pickFiles`, `pickSaveFile`, `clipboard`, `launchUri` / `launchFile` / `openFolder` / `revealInExplorer`, `share`, `NativeFile`, `DataTransfer`, `DragEvent` (opt-in; see Data transfer) |
+| `winui-svelte/incremental` | `src/incremental/index.ts` | `createIncrementalSource()`, `IncrementalSource`, `IncrementalStatus`, `IncrementalState` (opt-in; see Incremental loading) |
+| `winui-svelte/downloads` | `src/downloads/index.ts` | `Downloads` (`chrome.downloads`), `fetchToFile()`, `markOfTheWeb()`, `DownloadError` (opt-in; see Downloads) |
+| `winui-svelte/chrome/runtime` | `src/chrome/runtime/index.ts` | `Runtime` (`chrome.runtime`), `Port`, `InstallReason`, the native messaging codec (opt-in; see Chrome runtime) |
+| `winui-svelte/chrome/notifications` | `src/chrome/notifications/index.ts` | `ChromeNotifications` (`chrome.notifications`), `NotificationTemplateType`, `NotificationPermissionLevel` (opt-in; see Chrome notifications) |
+
+| `winui-svelte/chrome/commands` | `src/chrome/commands/index.ts` | `ChromeCommands` (`chrome.commands`), `parseShortcut()` (opt-in; see Chrome commands) |
+| `winui-svelte/chrome/action` | `src/chrome/action/index.ts` | `ChromeAction` (`chrome.action`), `createChromeAction()` (opt-in; see Chrome action) |
+| `winui-svelte/chrome/i18n` | `src/chrome/i18n/index.ts` | `ChromeI18n` (`chrome.i18n`), `installLanguageDefaults()` (opt-in; see Chrome i18n) |
+| `winui-svelte/chrome/install` | `src/chrome/install.ts` | `installChromeApis()`, `ChromeGlobal`, `ChromeAlarms`, `ChromeSystem` (opt-in; see Chrome global) |
 | `winui-svelte/input` | `src/input/index.ts` | `enableInputEvents()`, `setPointerCapture` / `releasePointerCapture` / `hasPointerCapture`, `activeElement()`, `moveFocus()`, `trapFocus()`, `PointerType`, `PointerEvent` / `WheelEvent` / `KeyboardEvent` / `FocusEvent` (opt-in; see Input events and focus) |
 | `winui-svelte/media` | `src/media/index.ts` | `bitmapImageOf()`, `svgImageSourceOf()`, `decodeDataUri()`, `createMediaPlayer()`, `mediaSourceOfBytes()`, `observePlayback()`, `PlaybackState` (opt-in; see Media) |
 | `winui-svelte/win2d` | `src/win2d/index.ts` | `Canvas`, the Win2D controls, the drawing helpers and Win2D classes, `applyEffect` (opt-in; see Win2D) |
 | `winui-svelte/enums` | `src/enums.ts` | every closed set a prop or option takes: WinUI's enums, `ThemeBrush`, `ColorKeyword`, `Backdrop`, `WindowTheme`, `TrayBalloonIcon` and the rest (see Closed sets) |
 | `winui-svelte/win2d/context-2d` | `src/win2d/context-2d/index.ts` | `Canvas2D`, `createCanvas2D`, `CanvasElement`, `Context2D`, `Path2D` and the rest of the HTML Canvas 2D API over Win2D (opt-in; see Canvas 2D) |
 | `winui-svelte/tray` | `src/tray/index.ts` | `TrayIcon` (with its `menu`), `createTrayIcon()`, `placeMenuWindow()`, `hideToTray()`, `restoreFromTray()`, `toggleInTray()`, `removeAllTrayIcons()`, `TrayGesture` (opt-in; see System tray) |
-| `winui-svelte/tray/standalone` | `src/tray/standalone/index.ts` | `createStandaloneTray()`, `NativeMenuEntryKind`, and the `winui-svelte/app` calls that start or signal the app: a tray with no window, no WinUI and no components (opt-in; see Tray with no window) |
+| `winui-svelte/progress/core` | `src/progress/core.ts` | `ProgressRegistry`, `defaultProgressRegistry()`, `ProgressOperation`, `trackOperation()`, `progressText()` and the types, with no Svelte component and no taskbar code, for a process with no window (opt-in; see Progress) |
+| `winui-svelte/tray/standalone` | `src/tray/standalone/index.ts` | `createStandaloneTray()`, `defineTray()`, its opt-in parts `balloons`, `bounds` and `themedIcon`, `MenuItemKind`, `MenuLevel`, and the `winui-svelte/app` calls that start or signal the app: a tray with no window, no WinUI and no components (opt-in; see Tray with no window) |
 | `winui-svelte/notice` | `src/notice/index.ts` | `showNotice()`, `NoticeIcon`, `NoticeButtons`, `NoticeButton`: a message box with no window or app (opt-in; see Notice with no app) |
 | `winui-svelte/forms` | `src/forms/index.ts` | `Form`, `FormField`, `textField`, `numberField`, `selectField` and the other field attachments, `formButton`, `FormValues`, `validityOf` (opt-in; see Forms) |
 | `winui-svelte/store` | `src/store/index.ts` | `getAppLicense`, `watchLicense`, `checkForUpdates`, `watchPackages`, `getStartupTask`, `getPackageInfo`: the Store and package APIs, answering `hasPackage: false` outside a package (opt-in) |
 | `winui-svelte/accessibility`, `/accessibility/audit` | `src/accessibility/index.ts`, `src/accessibility/audit/index.ts` | `announce`, `liveRegion`, `LivePriority`; `auditAccessibility`, `accessibilityRules` (opt-in; see Accessibility) |
+| `winui-svelte/automation` | `src/automation/index.ts` | `withUiaClient`, `createUiaWorker`, `readWindowText`, `UiaControlType`: a UI Automation client that reads the text of another window (opt-in; see UI Automation client) |
 | `winui-svelte/devices` | `src/devices/index.ts` | device enumeration, input devices, Bluetooth, printers, power, network, display, audio, gamepads and sensors, each also at `winui-svelte/devices/<area>` (opt-in; see Windows devices) |
 
 The table is the source layout: `exports` point at `.ts` files so the monorepo
@@ -740,11 +755,13 @@ type WindowOptions<Props> = {
   size?: { width: number; height: number };   // device pixels
   backdrop?: Backdrop;                        // "acrylic" | "acrylicBase" | "acrylicThin" | "mica" | "micaAlt" | "none" | "transparent"
   extendsIntoTitleBar?: boolean;
+  onclosing?: () => boolean | void;           // AppWindow.Closing: return true to keep the window open
   isBackground?: boolean;                     // shown without activating (tests, captures)
 } & ({ component: Component<Props>; props: Props } | { control: FrameworkElement });
 
 interface AppWindow<Props> {
   readonly window: Window;
+  readonly handle: WindowHandle;              // what chromeWindowSurface and the rest of the window API take
   readonly mounted: Mounted<Props> | null;    // null for a control
   close(): void;
   onClosed(listener: () => void): void;
@@ -1354,7 +1371,7 @@ const vertical: Orientation = 1;
 | A path geometry (`GeometryInput`, on `PathIcon` and `Path`) | Path Markup Syntax text or a `Geometry` | `data="M0,0 L10,10"` |
 | A font family (`FontFamilyInput`) | a family name or a `FontFamily` | `"Segoe UI Variable"` |
 | A grid length (`GridLengthInput`) | pixels, or `GridLengthText` as XAML writes it | `"Auto"`, `"2*"`, `"120"` |
-| The package's own | `Backdrop`, `WindowTheme`, `TitleBarHeight`, `WindowPresentation`, `PickerLocation`, `NavigationCacheMode`, `NavigationMode`, `MoveDirection`, `XamlKind`, `FocusKind`, `TrayGesture`, `TrayBalloonIcon`, `ConnectedAnimationKind` | `backdrop={Backdrop.mica}` |
+| The package's own | `Backdrop`, `WindowTheme`, `TitleBarHeight`, `WindowPresentation`, `PickerLocation`, `NavigationCacheMode`, `NavigationMode`, `MoveDirection`, `XamlKind`, `FocusKind`, `TrayGesture`, `TrayBalloonIcon`, `ConnectedAnimationKind`, `DialogResult`, `DialogButton` | `backdrop={Backdrop.mica}` |
 
 A WinUI enum's members keep WinUI's names and case (`"Minimal"`, not
 `"minimal"`), as the metadata and the docs have them; the package's own sets
@@ -2558,9 +2575,13 @@ An opt-in subpath: an app that does not import it does not bundle it
   redirects to it
   An app whose windows run in a worker thread passes `entryScript`, the script
   that starts the process, because `process.argv[1]` there is the worker's
+  A single executable application (a Node `node:sea` build, where
+  `process.execPath` is the app's own exe) is relaunched as the exe and
+  `arguments`, with no script and no Node flags
 - `restartAfterCrash({ arguments, conditions })` is
   `RegisterApplicationRestart`: Windows starts the same Node and entry
-  script with `arguments` after a crash, a hang, an update that closes the
+  script (a single executable: its own exe) with `arguments` after a crash,
+  a hang, an update that closes the
   app or a reboot for one; `conditions` is a subset of `RestartCondition`
   (`crash`, `hang`, `update`, `reboot`; all by default)
   Limits: no callback (a crashed Node cannot run code, so
@@ -2618,10 +2639,13 @@ if (!single.isPrimary) {
 - `ActivationEvent` is a union on `kind` (`ActivationKind`, also from
   `winui-svelte/enums`): `launch` (started by hand), `file` (`files`, absolute
   paths of existing files), `protocol` (`uri`, `scheme`), `startup` (started
-  at sign-in) and `redirect` (a later copy with nothing to open)
+  at sign-in), `redirect` (a later copy with nothing to open) and `jumpList`
+  (`taskId`, a task of the jump list was chosen; see Jump list tasks) and
+  `alarm` (`alarm`, an alarm of `winui-svelte/app/schedule` went off; it also
+  reaches `onAlarm`)
   Every event has `isRedirect`, `arguments` and `workingDirectory`; a link
   sent by a later copy is `protocol` with `isRedirect: true`
-- A link wins over files, files win over the startup marker; an argument
+- An alarm wins over a jump list task, a jump list task wins over a link, a link wins over files, files win over the startup marker; an argument
   that fits none stays in `arguments`
   Arguments are checked with a schema (up to 1024 of them, up to 32767
   characters each, no NUL); a failure goes to `onError`, the rest go on
@@ -2661,6 +2685,190 @@ if (!single.isPrimary) {
   `test/activation.test.ts` starts real second copies with a link, a file and
   nothing, and checks the first hears each as one event
 
+### Jump list tasks (`winui-svelte/app/jump-list`)
+
+Entries in the Tasks section of the taskbar button's right-click menu
+(`ICustomDestinationList`, `IObjectCollection` and `IShellLink`)
+No package identity is needed; an opt-in subpath
+Thumbnail toolbar buttons cannot be built from Node (their click is a sent
+message that no hook receives), so a task is the way to put a command there
+
+```ts
+import { startActivation } from "winui-svelte/app/activation";
+import { setJumpListTasks } from "winui-svelte/app/jump-list";
+
+const list = setJumpListTasks({
+  tasks: [
+    { id: "new-note", title: "New note", arguments: ["--new"] },
+    { id: "inbox", title: "Open inbox", arguments: ["--inbox"], icon: "inbox.ico" },
+  ],
+});
+
+startActivation({
+  key: "com.example.notes",
+  window: mainWindow,
+  onActivation(event) {
+    const task = list.taskOf(event);
+    if (task?.id === "new-note") newNote();
+  },
+});
+```
+
+- `setJumpListTasks({ tasks, appUserModelId, command })` replaces the Tasks
+  of the list and returns `{ tasks, taskOf(event) }`; `tasks` is a `const`
+  generic, so `task.id` is the union of your ids
+- `clearJumpList({ appUserModelId })` deletes the whole list
+- A `JumpListTask` is `{ id, title, arguments, description, icon, iconIndex,
+  workingDirectory }`; `id` is letters, digits, `_`, `.` and `-`, 64 at most,
+  and unique; `icon` is a file path (`PictureSource`, but a `data:`, `http(s)`
+  or `ms-appx` URI is a `TypeError`): an .ico, or an .exe or .dll with
+  `iconIndex`
+- A click starts `command` (this process's Node and entry script by default,
+  as `registerFileTypes` does; a bundled executable passes its own) with the
+  marker `--winui-svelte-jump-list=<id>` and then the task's `arguments`,
+  quoted for `CommandLineToArgvW`
+  `startActivation` hands that to the running copy through the single
+  instance redirect as a `jumpList` event: `taskId` is the id and `arguments`
+  are the task's own; a first start gets the same event with `isRedirect:
+  false`
+- The list belongs to the process's AppUserModelID and Windows shows nothing,
+  without an error, when a window has another; so the call throws when the
+  process has none (give `<Window>` an `appUserModelId`, or call
+  `joinAppUserModel`) or when `appUserModelId` differs from it
+- Keep the tasks static, as Microsoft advises: set them once at start
+- Call it on a thread with COM (the UI thread of a window has it)
+- `src/app/jump-list/native.test.ts` commits a list under a unique
+  AppUserModelID in the test process, checks that Windows wrote its
+  custom destinations file, and deletes the list, even when it fails
+
+### Shell verbs (`winui-svelte/app/shell`)
+
+What Explorer's context menu does, from code
+There is no web API for these; the names follow the launcher helpers of
+`winui-svelte/data-transfer`, which stay the home of `launchUri`,
+`launchFile`, `openFolder` and `revealInExplorer`
+An opt-in subpath: an app that does not import it does not bundle it
+
+```ts
+import { createShortcut, openWith, readShortcut, registerAppPath, trash } from "winui-svelte/app/shell";
+
+const result = trash({ paths: ["C:\\Users\\me\\old.txt"] });
+if (!result.ok) console.warn(result.reason, result.message);
+
+createShortcut({
+  path: "C:\\Users\\me\\Desktop\\Notes.lnk",
+  target: "C:\\Apps\\notes.exe",
+  arguments: ["--open", "my notes.txt"],
+  workingDirectory: "C:\\Apps",
+  icon: { path: "C:\\Apps\\notes.exe", index: 0 },
+  description: "Open my notes",
+});
+const link = readShortcut({ path: "C:\\Users\\me\\Desktop\\Notes.lnk" });
+await openWith({ path: "C:\\Users\\me\\photo.png" });
+registerAppPath({ name: "notes", program: "C:\\Apps\\notes.exe" });
+```
+
+- Every verb returns `{ ok: true }` or `{ ok: false, reason, message }`;
+  `reason` is a `ShellFailure` (`invalid`, `not-found`, `exists`,
+  `owned-by-another`, `aborted`, `failed`)
+- These act on the user's own files; they check and then act, and none
+  asks the user first
+- Paths are data: each must be a full path with no control character and not a
+  device path; none is built into a command line
+- `trash` sends to the Recycle Bin (`SHFileOperationW` with
+  `FOF_ALLOWUNDO`) and never deletes for good; when Windows would have to
+  (a drive without a bin, a file too big for it) it asks, and nothing goes
+  unless the user agrees; all the paths are checked before any is touched
+- `openWith` shows the Windows "Open with" list for a file
+  (`LauncherOptions.DisplayApplicationPicker`), so it takes a file and never a
+  program; it opens a dialog and is only unit-tested with a fake
+- `createShortcut` writes only the `.lnk` file (`IShellLink` and
+  `IPersistFile`); each argument is quoted by the same rule as the
+  activation registrations, and an existing file is kept unless
+  `shouldOverwrite` is set; the target is not required to exist
+- `readShortcut` gives the target as stored, without searching for a moved
+  one and without running anything
+- `registerAppPath` writes a key under `HKEY_CURRENT_USER` (App Paths) with a
+  marker value, only when the key is free or the package made it;
+  `unregisterAppPath` removes only a key with the marker; the name is an
+  identifier that is not a name Windows or a common tool answers to, and the
+  program is a full path ending in `.exe`; the machine-wide hive is out of reach
+- A shortcut that carries an AUMID (for toast identity) is not offered yet
+- `src/app/shell/native.test.ts` recycles a file, writes and reads a
+  shortcut in a folder it creates under the temp directory and removes, and
+  registers and removes an App Paths alias with a unique name
+
+### Alarms (`winui-svelte/app/schedule`)
+
+Starts the app at a time, once or on a repeat, through Task Scheduler, and
+tells it which alarm went off
+The shape is `chrome.alarms` (`create`, `get`, `getAll`, `clear`, `clearAll`,
+`onAlarm`, the `Alarm` type) with promises instead of callbacks, and
+`chrome.runtime.onStartup` for the start at sign-in
+An opt-in subpath: an app that does not import it does not bundle it
+
+```ts
+import { ActivationKind, startActivation } from "winui-svelte/app/activation";
+import * as alarms from "winui-svelte/app/schedule";
+
+alarms.onAlarm.addListener(alarm => sync(alarm.name));
+alarms.onStartup.addListener(() => restoreSession());
+startActivation({ key: "my-app", onActivation: () => {} });
+
+await alarms.create("nightly-sync", { when: Date.now() + 3_600_000, periodInMinutes: 1440 });
+await alarms.get("nightly-sync"); // { name, scheduledTime, periodInMinutes: 1440 }
+await alarms.getAll(); // every alarm this package made
+await alarms.clear("nightly-sync"); // true
+await alarms.clearAll(); // false
+```
+
+- `create(name, { when, delayInMinutes, periodInMinutes })` is Chrome's:
+  `when` is milliseconds since 1970, `delayInMinutes` counts from now, and
+  with only `periodInMinutes` the first run is one period away; `when` and
+  `delayInMinutes` together, or none of the three, throw; creating a name again
+  replaces its alarm
+  - `name` is letters, digits, `.`, `_` and `-` (a task name, not free text)
+  - Chrome's one-minute minimum for `delayInMinutes` is not applied: a delay
+    can be seconds, and a time in the past runs at once
+  - `periodInMinutes` is 1 to 44640 (Task Scheduler cannot repeat faster than
+    a minute, nor slower than 31 days)
+  - Extras, optional members of the same object: `arguments` (reach the
+    started copy after the entry script), `runWhenOnBattery` (true by
+    default), `command` (a bundled executable instead of Node) and `backend`
+    (a test)
+- `get`, `getAll`, `clear` and `clearAll` read and remove only the tasks in the
+  `winui-svelte` folder of Task Scheduler, so a task of another program can
+  neither be listed nor removed from here; `scheduledTime` is the next run
+- `onAlarm` and `onStartup` have `addListener`, `removeListener` and
+  `hasListener`; they are called by `startActivation`, so call it for the
+  alarms to arrive
+  - A task runs the app again with a marker argument, which becomes an `alarm`
+    activation (`event.alarm`) and also reaches `onAlarm`; if the app is open,
+    the new copy hands the activation to it and exits, so the listener of the
+    running app hears it, and if it is closed, the started copy hears it
+  - `onStartup` is called for a `startup` activation, that is when Windows
+    starts the app at sign-in; turning that start on or off is `launchAtLogin`
+    of `winui-svelte/app/activation` (the Run key listed in Settings, Apps,
+    Startup), which this module does not repeat
+- How it works: the package writes a Task Scheduler 1.2 XML definition to a
+  private temporary file and runs `schtasks.exe /Create /XML` (found by
+  `SystemRoot`), so no COM is involved; the task runs as the signed-in user
+  with normal rights (no administrator), with no time limit, and a start
+  missed while the PC was off is made up when it is next on; the alarm's first
+  time and period are kept in the task's description, which is how `get`
+  reads them back
+- A one-shot alarm's task deletes itself a day after its time
+- Limits:
+  - The task runs only while the user is signed in
+  - `schtasks` is the only gate: Group Policy can forbid task creation, and
+    then `create` rejects with its message
+  - Moving or reinstalling the app leaves a task that points at the old path
+    until the alarm is created again
+- `src/app/schedule/schedule.test.ts` checks the generated XML, the quoting
+  and escaping of arguments, the marker argument and the activation it
+  becomes, and an alarm's round trip to a task and back over a fake backend; no
+  real task is made
+
 ### Global hotkeys (`winui-svelte/app/hotkeys`)
 
 A system-wide key combination, heard whichever app has the focus
@@ -2726,6 +2934,65 @@ const hotkey = registerHotkey({
   posts `WM_HOTKEY` to the thread itself with `PostThreadMessageW`; no key is
   pressed
 
+### Following the foreground app (`winui-svelte/window/foreground`)
+
+Opt-in; nothing runs at import
+
+```ts
+import {
+  bringWindowToFront,
+  shouldRestore,
+  trackForeground
+} from "winui-svelte/window/foreground";
+
+const tracker = trackForeground({
+  ownWindows: () => [pillHwnd],
+  onChanged: ({ hwnd, isRealApp }) => {}
+});
+tracker.lastRealApp; // bigint | null, the last real app that was in front
+tracker.current; // bigint | null
+tracker.stop(); // idempotent
+
+const isBack = shouldRestore({
+  lastRealApp: tracker.lastRealApp,
+  foreground: tracker.foreground
+});
+if (isBack && tracker.lastRealApp !== null) {
+  bringWindowToFront(tracker.lastRealApp); // true when Windows took it
+}
+```
+
+- `trackForeground({ onChanged, ownWindows, ignoredClasses, tracking,
+  intervalMilliseconds })` runs on the UI thread of a `runWindow` app
+- `tracking: "events"` (default, `ForegroundTracking.events`): the shell posts
+  a message to a hidden window of the app on each change
+  (`RegisterShellHookWindow` and `SHELLHOOK`), the message pump reads it, and
+  `GetForegroundWindow` is read once; an idle foreground costs nothing
+  dynwinrt delivers no native callbacks, so `SetWinEventHook` cannot be used
+  If Windows refuses the registration, use `tracking: "polling"`
+- `tracking: "polling"`: one `GetForegroundWindow` per `intervalMilliseconds`
+  (100 by default, 16 at least); latency is one tick
+  The class and the process of a window are read once, when it is first seen
+- The filter: a real app is not the desktop, not a shell class
+  (`ForegroundShellClass`: `Progman`, `WorkerW`, `Shell_TrayWnd`,
+  `Shell_SecondaryTrayWnd`, `CopilotKeyPressFocusFrame`), not a window of
+  this process, and not in `ownWindows()` or `ignoredClasses`
+  `lastRealApp` changes only on a real app
+- `bringWindowToFront(hwnd)` joins this thread to the foreground thread's
+  input for `BringWindowToTop` and `SetForegroundWindow`, then detaches,
+  because a hotkey's key releases went to the app in front and Windows'
+  foreground lock refuses a plain call; it restores a minimized window first,
+  sends no input and returns whether the window ended in front
+  It is best effort: a foreground window of a higher integrity level or a hung
+  one still refuses; the tray menu window takes the foreground through it
+- Not measured yet: the idle cost of each mode (the tray's 30 Hz timer costs
+  about 2 percent of a core in an idle window)
+
+Manual checklist: press the app's hotkey from Notepad, then from the desktop,
+then from a browser on a second monitor; each time the key goes back to where
+it was; then Alt+Tab to another app while the overlay is up and confirm it is
+not pulled back
+
 ### System tray (`winui-svelte/tray`)
 
 WinUI and the Windows App SDK have no notification-area API (apps call
@@ -2847,6 +3114,239 @@ window's content
 A Tauri or Electron host that already has a tray should keep it: two icons
 would show, and this one lives and dies with the WinUI window's process
 
+### One tray menu for every renderer (`winui-svelte/tray/menu`)
+
+A pure model of a tray menu: no WinUI, no Win32, so it runs under
+`node --test` and in a tray-only bundle
+You declare items once; the user picks how much of the menu to see, from the
+simple menu of a dictation app to the long one of a screenshot tool, and then
+hides, shows and reorders single items; a renderer draws what `resolveMenu`
+returns
+An opt-in subpath: an app that does not import it does not bundle it
+
+```ts
+import { defineMenu, MenuItemKind, MenuLevel, resolveMenu } from "winui-svelte/tray/menu";
+
+// The simple style: three commands and a separator, no levels set
+const simple = defineMenu([
+  { kind: MenuItemKind.COMMAND, id: "toggle", label: "Start dictation" },
+  { kind: MenuItemKind.COMMAND, id: "settings", label: "Settings" },
+  { kind: MenuItemKind.SEPARATOR, id: "line" },
+  { kind: MenuItemKind.COMMAND, id: "quit", label: "Quit", isRequired: true }
+]);
+
+// The complex style: the same model with levels
+const complex = defineMenu([
+  { kind: MenuItemKind.HEADER, id: "capture-header", label: "Capture" },
+  {
+    kind: MenuItemKind.SUBMENU,
+    id: "capture",
+    label: "Capture",
+    items: [
+      { kind: MenuItemKind.COMMAND, id: "region", label: "Region", shortcut: "Ctrl+Shift+4" },
+      { kind: MenuItemKind.COMMAND, id: "scroll", label: "Scrolling", level: MenuLevel.FULL }
+    ]
+  },
+  {
+    kind: MenuItemKind.SUBMENU,
+    id: "recent",
+    label: "Recent uploads",
+    level: MenuLevel.STANDARD,
+    emptyLabel: "Nothing uploaded yet",
+    maxItems: 10,
+    items: () => recentUploads().map(({ name }) => ({ kind: MenuItemKind.COMMAND, id: `recent-${name}`, label: name }))
+  },
+  {
+    kind: MenuItemKind.CHECK,
+    id: "autostart",
+    label: "Start with Windows",
+    level: MenuLevel.STANDARD,
+    isChecked: () => isAutostart(),
+    staysOpen: true
+  },
+  { kind: MenuItemKind.COMMAND, id: "quit", label: "Quit", isRequired: true }
+]);
+
+// Call it each time the menu opens: functions are read now
+const lines = resolveMenu({
+  items: complex,
+  profile: { level: MenuLevel.STANDARD, hidden: ["region"], shown: [], order: {} }
+});
+```
+
+- `MenuItem` is a union on `kind`: `command`, `check`, `radio`, `submenu`,
+  `separator` and `header` (`MenuItemKind`); a field belongs to the kinds that
+  have it, so a command with `isChecked` or a radio with no `group` fails to
+  compile
+- Every item has a unique, stable `id`; the profile of the user is keyed by it
+  `defineMenu` keeps the ids as literal types, and `MenuProfile` typed with
+  `MenuIds` of the menu (and the `profile` of `resolveMenu`) rejects an id
+  that is not in the menu
+- `level` is the lowest detail level that shows the item (`MenuLevel`:
+  `simple`, `standard`, `full`; `simple` when left out); `isRequired` cannot
+  be hidden by the user
+- `label`, `isEnabled`, `isVisible`, `isChecked`, `isBold` and `badge` may be
+  a value or a function, read each time `resolveMenu` runs
+- `items` of a submenu may be a function that makes the children each time;
+  `sort` and `maxItems` order and cap such a list, and `emptyLabel` shows a
+  disabled line when it is empty instead of dropping the submenu
+- `staysOpen` keeps the menu open after the pick (the renderer then refreshes
+  labels and ticks only); `closeThenRun` (true unless set to false) runs
+  `onselect` after the menu has closed, so that a dialog can open
+- A submenu may have its own `onselect` and `autoExpand`
+- `icon` is a path, a glyph or `IconPixels`; `shortcut` is display text only,
+  the menu does not bind the key
+- `MenuProfile` is plain JSON: `level`, `hidden` (ids the level shows that
+  the user hid), `shown` (ids above the level that the user turned on) and
+  `order` (child ids in the user order, keyed by parent id, `""` for the root)
+- `resolveMenu({ items, profile })` returns `ResolvedMenuItem[]`: final text,
+  booleans and a `select()` per line, with separators collapsed, headers with
+  nothing under them dropped and empty submenus dropped; it throws
+  `MenuModelError` for a repeated id or a radio with no group
+- `describeMenu({ items })` lists every item with its id, kind, label, level,
+  parent id and `isRequired`, for an editor
+- `defaultProfile({ level })`, `parseProfile({ value })` and `profileSchema`
+  (a field that is wrong falls back to its default, nothing throws),
+  `loadProfile({ file })` and `saveProfile({ file, profile })` (the file is
+  replaced atomically)
+- Not in the model: the actions of the icon itself (left, double and middle
+  click) stay on the tray icon options
+
+### The tray menu in a window (`winui-svelte/tray/menu/svelte`)
+
+The model of `winui-svelte/tray/menu` drawn by `<TrayIcon>` as a WinUI
+`MenuFlyout`, from an array or from markup
+An opt-in subpath; a consumer that imports only `winui-svelte/tray/menu`
+bundles no Svelte and no component
+
+```svelte
+<script lang="ts">
+  import { MenuLevel } from "winui-svelte/enums";
+  import { TrayIcon } from "winui-svelte/tray";
+  import { TrayMenu, TrayMenuItem, TrayMenuSeparator, TrayMenuSubmenu } from "winui-svelte/tray/menu/svelte";
+
+  let isAutostart = $state(false);
+  let recent = $state(["a.png", "b.png"]);
+</script>
+
+<TrayIcon icon="app.ico" tooltip="My app">
+  <TrayMenu profile={savedProfile}>
+    <TrayMenuItem id="open" label="Open" onselect={showWindow} />
+    <TrayMenuItem id="autostart" kind="check" label="Start with Windows"
+      isChecked={isAutostart} level={MenuLevel.STANDARD} staysOpen
+      onselect={() => (isAutostart = !isAutostart)} />
+    <TrayMenuSubmenu id="recent" label="Recent" emptyLabel="Nothing yet">
+      {#each recent as name (name)}
+        <TrayMenuItem id={`recent.${name}`} label={name} />
+      {/each}
+    </TrayMenuSubmenu>
+    <TrayMenuSeparator id="line" />
+    <TrayMenuItem id="quit" label="Quit" isRequired onselect={quit} />
+  </TrayMenu>
+</TrayIcon>
+```
+
+- `<TrayIcon menu={items} profile={profile}>` takes the array of
+  `defineMenu` instead of markup, or the `menu` snippet of a hand-written
+  flyout as before; the three never mix
+  The ids of the array stay literal, so `profile` rejects an id the menu does
+  not have
+- `<TrayMenu>` and its children are inert elements: they draw nothing, the
+  tray walks the tree each time the menu opens, so order, nesting, `{#if}`,
+  keyed `{#each}` and reactive props all work, with no second renderer
+- The props are the fields of the model's own items (`TrayMenuItem` takes a
+  `kind` of `command`, `check` or `radio`; a tick on a command or a radio with
+  no `group` fails `svelte-check`), and an unknown attribute fails too
+- Markup cannot carry a literal union, so ids written in markup are plain
+  `string`; the exported `collectMenu` reads a `TrayMenu` element into the same
+  `MenuItem[]`
+- A `TrayMenu` has a `profile` of its own, used for its lines
+  `profile` on `TrayIcon` applies to `menu={items}`
+- The flyout is built from `resolveMenu` each time the menu opens: a command is
+  a `MenuFlyoutItem`, a check a `ToggleMenuFlyoutItem`, a radio a
+  `RadioMenuFlyoutItem` (its `group` is the `GroupName`), a submenu a
+  `MenuFlyoutSubItem`, a header a disabled bold item
+  `isBold` is the font weight; `icon` is drawn as a glyph (`FontIcon`) or, for
+  a path to an `.ico` or `.png`, an `ImageIcon`; `IconPixels` is not drawn
+  A flyout has one trailing column, the keyboard accelerator's, so it shows
+  the `badge` and then the `shortcut` as text
+- `onselect` runs after the flyout has closed, on the next turn
+  (`closeThenRun`, true unless set to false)
+- `staysOpen`: WinUI closes a flyout when an item is invoked, and offers no
+  property to keep it open, so the item runs after the close and the flyout is
+  built again from the model, at the same point, with the new labels and ticks
+  The menu blinks once; every other pick closes the menu
+- `TrayMenuFlyout` (from `winui-svelte/tray`) is that flyout on its own: put
+  it in a `menu` snippet with `resolve={() => resolveMenu({ items })}` and
+  `onclose={close}`; `onflyout` hands over the native `MenuFlyout` to read
+- Not drawn by WinUI: a submenu row's own `onselect` (a `MenuFlyoutSubItem` has
+  no click) and `autoExpand` (it has no member to open it from code)
+
+### Letting the user customize the tray menu (`winui-svelte/tray/menu/svelte`)
+
+`<TrayMenuEditor>` is the settings control for a tray menu: the user picks how
+much of it shows, from three lines to a ShareX-like menu "and everything in
+between"
+It edits a `MenuProfile` and says so; it never reads or writes a file
+
+The three levels are the `level` of each item (`simple` when left out):
+
+| Level | The user gets | Shown items |
+|---|---|---|
+| Simple | The few lines every user needs | Items of level `simple` |
+| Standard | The usual set | `simple` and `standard` |
+| Full | Everything the app can do | All |
+
+```svelte
+<script lang="ts">
+  import { TrayIcon } from "winui-svelte/tray";
+  import { loadProfile, saveProfile } from "winui-svelte/tray/menu";
+  import { TrayMenuEditor } from "winui-svelte/tray/menu/svelte";
+  import { items } from "./menu.ts";
+
+  const FILE = "tray-menu.json";
+  let profile = $state(loadProfile({ file: FILE }));
+</script>
+
+<TrayMenuEditor {items} isPreviewShown bind:profile
+  onchange={next => saveProfile({ file: FILE, profile: next })} />
+
+<TrayIcon icon="app.ico" menu={items} {profile} />
+```
+
+| Prop | Meaning |
+|---|---|
+| `items` | The menu `defineMenu` declares; the ids stay literal |
+| `profile` | The user's choice, bindable; the default profile when left out |
+| `onchange(profile)` | Runs with the new profile after every edit; save it here |
+| `onsave(profile)` | Adds a Save button that runs this, for an app that saves on request |
+| `labels` | The strings of the editor, each optional and English by default (`DEFAULT_EDITOR_LABELS`); `{name}` stands for an item's label |
+| `isPreviewShown` | Lists the menu as it resolves under the profile, as plain rows |
+
+- The detail level is three radio buttons: Simple, Standard, Full
+  Changing it keeps the user's tweaks: an item the user hid stays hidden at
+  every level, and one the user turned on above the level stays on
+  The word "Custom" appears beside the level while the profile has any tweak
+  (a hidden or shown item, or a menu in another order); the level alone is not
+  a tweak
+- Below it is a tree of every item (`describeMenu`), submenus with their
+  children indented
+  Each row has a check for "shown" (what the level, `hidden` and `shown` make
+  of it), the lowest level that includes the item as text, and Up and Down
+  buttons that move it within its own menu (the whole tree is reachable with
+  Tab, Space and Enter, and no operation needs a drag)
+- An item with `isRequired` is locked on and says "Always shown"
+- "Reset to default" returns to `defaultProfile()` and is disabled while the
+  profile already is that
+- Every control has an `automationName`, the title and sections are headings,
+  and no state is told by color alone
+- The functions behind it are pure and tested without a window:
+  `src/tray/menu-svelte/edit-profile.ts` (`setLevel`, `setItemShown`,
+  `moveItem`, `editorRows`, `hasTweaks`)
+- `examples/tray-menu-editor` puts the editor beside the tray icon it edits, on
+  a ShareX-like menu with Capture, Upload and Tools submenus, a dynamic recent
+  list, a check item and a required Exit; its simple level is a three-line menu
+
 ### Tray with no window (`winui-svelte/tray/standalone`)
 
 A tray that runs in a process of its own, plain Node, with no `Window`, no
@@ -2861,7 +3361,7 @@ for the menu and its timers run on the dispatcher queue
 import {
   activateOrLaunch,
   createStandaloneTray,
-  NativeMenuEntryKind
+  MenuItemKind
 } from "winui-svelte/tray/standalone";
 
 function openPanel() {
@@ -2877,26 +3377,77 @@ createStandaloneTray({
   tooltip: "Panel",
   onclick: openPanel,
   menu: [
-    { kind: NativeMenuEntryKind.COMMAND, label: "Open", onselect: openPanel },
-    { kind: NativeMenuEntryKind.SEPARATOR },
-    { kind: NativeMenuEntryKind.COMMAND, label: "Quit", onselect: () => process.exit(0) }
+    { kind: MenuItemKind.COMMAND, id: "open", label: "Open", onselect: openPanel },
+    { kind: MenuItemKind.SEPARATOR, id: "line" },
+    { kind: MenuItemKind.COMMAND, id: "quit", label: "Quit", onselect: () => process.exit(0) }
   ]
 });
 ```
 
 - `createStandaloneTray(options)` takes the icon's options (`icon`,
   `tooltip`, `isVisible`, `guid`, `onclick`, `ondoubleclick`,
-  `onmiddleclick`) and `menu`, and returns the same handle as
-  `createTrayIcon` (`update`, `notify`, `bounds`, `isRegistered`, `remove`)
+  `onmiddleclick`), `menu`, `extras`, and `resolve` with `profile`, and returns
+  a handle with `update`, `isRegistered` and `remove`, plus `notify` and
+  `bounds` when their extras are passed
   The icon keeps the process alive; `remove()` or the process ending takes it
   out of the tray
+- `colorScheme` is the menu's `color-scheme` as the web says it: `"light dark"`
+  (the default) makes the popup dark when Windows' app theme is, `"light"` and
+  `"dark"` force one; `MenuColorScheme` names the three values
+  It uses uxtheme's `SetPreferredAppMode` and `FlushMenuThemes` (ordinals 135
+  and 136), applied before each menu opens, so it affects the process's other
+  native menus too
+- The default is the smallest tray: an icon from one `.ico` path, clicks,
+  `update`, `remove` and the menu
+  Three parts are opt-in, each one import from the same entry, passed in
+  `extras`, and none of their code is in the bundle unless passed:
+  `balloons` adds `notify`, `bounds` adds `bounds()`, and `themedIcon` lets
+  `icon` be `{ forLightTaskbar, forDarkTaskbar }`, swapped as the taskbar theme
+  changes
+  The handle has `notify` or `bounds` only when its extra is passed, and a
+  theme pair is accepted only with `themedIcon`; otherwise it fails to compile
+  `createTrayIcon` and `TrayIcon` of `winui-svelte/tray` include all three
+
+```ts
+import { balloons, bounds, createStandaloneTray, themedIcon } from "winui-svelte/tray/standalone";
+
+const tray = createStandaloneTray({
+  icon: { forLightTaskbar: "dark.ico", forDarkTaskbar: "light.ico" },
+  extras: [balloons, bounds, themedIcon]
+});
+tray.notify({ title: "Ready" });
+```
+
 - The menu is Windows' own popup menu (`TrackPopupMenuEx`), made on a right
   click and destroyed when it closes; nothing of it exists while idle
-  A command is `{ kind, label, onselect, isEnabled }`, a line is
-  `{ kind: NativeMenuEntryKind.SEPARATOR }`
+  `menu` is the same model as the windowed tray's (`winui-svelte/tray/menu`):
+  commands, checks, radios, submenus to any depth, separators and headers,
+  each with an `id` (a separator too), and values that are functions are read
+  each time the menu opens, as are lazy submenu `items`
+  The menu is drawn by the lite resolver by default: every item is shown in
+  declared order, with dynamic values, `isVisible`, `emptyLabel`, `sort` and
+  `maxItems` applied, and `level` and `isRequired` ignored; it leaves the
+  level and profile code out of the bundle
+  For levels, a user profile and ordering, opt in with one import:
+  `resolve: resolveMenu` from the same entry, and then `profile`, the user's
+  choice of level, hidden, shown and order (a `MenuProfile` with a
+  `MenuLevel`, or a function that gives one, for example from
+  `loadProfile`)
+  The ids are literal types: `profile` accepts only ids of `menu`, and a
+  wrong one fails to compile; a `profile` without `resolve: resolveMenu` also
+  fails to compile, so a profile is never ignored in silence
+  Windows draws a check as a tick, a radio as a dot, a header as a disabled
+  bold line, a shortcut right-aligned and a badge after the label
+  `staysOpen` closes and reopens the menu at the same point, with fresh
+  labels and ticks, right after the line runs; `onselect` otherwise runs on
+  the next turn after the menu is gone (`closeThenRun: false` runs it as the
+  menu closes)
+  A submenu's own `onselect` and `autoExpand`, and every `icon`, do nothing
+  here: Windows opens a submenu row without reporting a pick, and no pixel
+  or file icon is drawn
   The menu is modal: the thread runs its own message loop until it closes
-  It does not follow a dark system theme, which a native popup menu does not
-  without an undocumented call; a menu that must match the theme belongs in
+  `colorScheme` makes it follow the system theme through an undocumented
+  uxtheme call; a menu that must be drawn in WinUI belongs in
   `winui-svelte/tray` with `TrayIcon`'s `menu` snippet
 - The same entry re-exports `activateInstance`, `activateOrLaunch` and
   `launchApp` from `winui-svelte/app` (App lifecycle), so a tray imports from
@@ -2907,6 +3458,234 @@ createStandaloneTray({
   component, window or renderer module, or a component's name, is in the
   output, or if it grows past its budget
 
+### Trays and windows are independent
+
+Neither needs the other
+A process can have zero windows and several tray icons, or windows and
+taskbar buttons and no tray; nothing is created for the part you leave out
+
+```ts
+// Zero windows, two icons, one Node process
+import { createStandaloneTray, MenuColorScheme, MenuItemKind } from "winui-svelte/tray/standalone";
+import { defaultProgressRegistry, progressText } from "winui-svelte/progress/core";
+
+createStandaloneTray({
+  icon: "recorder.ico",
+  tooltip: "Recorder",
+  colorScheme: MenuColorScheme.DARK,
+  menu: () => [{
+    kind: MenuItemKind.COMMAND,
+    id: "status",
+    label: progressText(defaultProgressRegistry().snapshot),
+    onselect() {}
+  }]
+});
+
+createStandaloneTray({
+  icon: "uploads.ico",
+  tooltip: "Uploads",
+  colorScheme: MenuColorScheme.LIGHT,
+  menu: [{ kind: MenuItemKind.COMMAND, id: "quit", label: "Quit", onselect: () => process.exit(0) }]
+});
+```
+
+```svelte
+<!-- Windows and a taskbar button, no tray -->
+<script lang="ts">
+  import { Window } from "winui-svelte/components";
+  import { TaskbarProgress } from "winui-svelte/progress";
+</script>
+
+<Window>
+  <TaskbarProgress />
+</Window>
+```
+
+- Each `createStandaloneTray` has an identity of its own (its own hidden owner
+  window and a unique id, and its own `guid` when you pass one), its own
+  timer, its own menu and its own state; `remove()` takes out that icon only
+  and the exit hook takes out all of them
+- Clicks are polled, and Windows keeps one "pressed since the last read"
+  flag for the whole process, which the first read clears; the trays of a
+  process share that read, so each icon hears a click shorter than its
+  polling interval (the flag can still be cleared by another process or by
+  other code of yours that calls `GetAsyncKeyState`)
+- The menu theme is one setting per process (uxtheme's preferred app mode);
+  a tray sets its own `colorScheme` right before each of its menus opens, so
+  two trays with different schemes each get theirs, because only one menu is
+  open at a time
+  The setting then stays until the next menu opens, so another popup menu in
+  the same process (a window's) shows in the scheme of the tray that spoke
+  last
+- `winui-svelte/progress/core` is the progress registry, operations and
+  `progressText` with no Svelte component and no taskbar code, so a
+  tray-only process can show progress; `winui-svelte/progress` adds
+  `TaskbarProgress` and `bindTaskbarProgress`, which are the only part that
+  needs a window
+- `scripts/pack/independence.test.ts` walks the imports and fails if the
+  standalone tray reaches a component, the renderer, the window runtime or
+  taskbar code, if the taskbar progress reaches a tray, or if a window
+  reaches a tray; `scripts/pack/tray-only.test.ts` bundles two trays with the
+  registry and fails on the same, or on a growing size
+
+### Tray as an entrypoint (`entrypoints/tray.ts`)
+
+The app does not have to know it has a tray; the tray is its own file, found
+by its name and built into a small bundle for a process of its own
+
+```text
+my-app/
+  entrypoints/
+    main.ts      -> dist/main.js
+    window.ts    -> dist/window.js
+    tray.ts      -> dist/tray.js, dist/tray.json, dist/tray.ico
+```
+
+`main.ts` and `window.ts` never import `tray.ts`; `buildApp` (and the dev
+server of `winuiSvelte()`) discover the folder, so `entries` is optional, and a
+name given in `entries` wins over the file found
+
+```ts
+import { activateOrLaunch, defineTray, MenuItemKind, MenuLevel, resolveMenu } from "winui-svelte/tray/standalone";
+
+export default defineTray({
+  icon: "tray.ico",
+  tooltip: "My app",
+  guid: "7d1c5a52-3f1b-4a63-9f5e-2f4d6b0c8a11",
+  onactivate: openApp,
+  resolve: resolveMenu,
+  menu: [
+    { kind: MenuItemKind.COMMAND, id: "open", label: "Open", isRequired: true, onselect: openApp },
+    { kind: MenuItemKind.COMMAND, id: "capture", label: "Capture", level: MenuLevel.STANDARD }
+  ]
+});
+```
+
+- `defineTray` returns its argument; it takes the options of
+  `createStandaloneTray` (`menu`, `resolve`, `profile`, `extras`, the click
+  handlers) with the ids of `menu` as a literal union, so a `profile` that names
+  an id the menu lacks is a type error, and `profile` needs `resolve`
+- `guid` is required: it keeps the icon's place in the tray and names the one
+  tray process, so a second `tray.js` exits at once
+- `onactivate` runs on a left click when `onclick` is not given
+- `export default [defineTray({ ... }), defineTray({ ... })]` defines several
+  trays in one entrypoint: one `tray.js`, one process, each tray with its own
+  `guid`, icon, tooltip, menu and `colorScheme` (every `guid` must differ)
+  The first tray's `guid` names the process, so keep the order; `tray.json` is
+  the single manifest for one tray and `{ "trays": [ ... ] }` for several, and
+  `startTray()` reads the first `guid` from either
+  The markup form (`tray.svelte`) is one tray; use `tray.ts` for several
+  `examples/tray-multiple` is a two-icon entrypoint with no window
+- The build reads `icon`, `tooltip` and `guid` from the syntax tree, never by
+  running the file, so a top-level import of WinRT in `tray.ts` does not
+  execute at build; `icon` and `guid` must be string literals, and the icon a
+  file inside the folder of `tray.ts` (written there as `icon: "tray.ico"`,
+  copied to the same relative path in the output)
+- `tray.js` is the wrapper the build writes (a virtual module, like WXT's
+  background): it imports the default export, calls `claimTrayInstance({ guid })`
+  (the right to be the one tray for the `guid`; false in a second copy) and then
+  `createStandaloneTray`; `tray.json` holds what was read
+- `startTray()` from `winui-svelte/app` starts `tray.js` detached once; it is
+  optional, for an installer, a launcher or the app's own start; it reads
+  `tray.json` for the `guid`, so the key is derived in one place
+  (`trayInstanceKey(guid)`); `activateOrLaunch` is how the tray reaches the app
+- Under the dev server the tray is built into `.winui/tray` and started; a
+  change to it rebuilds and restarts the process (no HMR, as WXT's background)
+  after stopping the Node process whose pid `.winui/tray.pid` holds
+- The icon of a stopped process stays in the notification area until the
+  pointer passes over it; that is how Windows handles an icon whose process
+  was ended
+- The bundle holds no component and no window runtime; most of its size is
+  zod, which a bundle for Node carries (`scripts/pack/tray-entrypoint.test.ts`
+  keeps its budget)
+- `tray.svelte` is the same entrypoint written as markup (next section); a
+  folder with both `tray.ts` and `tray.svelte` is an error
+
+The working example is `examples/tray-entrypoint`
+
+#### The tray written as markup (`entrypoints/tray.svelte`)
+
+The menu can be written with the components of
+`winui-svelte/tray/menu/svelte`; the build reads the file with Svelte's parser
+and lowers the markup to the plain model of `tray.ts`, so none of Svelte's
+runtime is in `tray.js` (about 40 KB that a tray-only process cannot carry)
+
+```svelte
+<script module lang="ts">
+  import { activateOrLaunch, resolveMenu } from "winui-svelte/tray/standalone";
+
+  let isAutostart = false;
+
+  function openApp() {
+    void activateOrLaunch({ key: "my-app", activation: { arguments: [], workingDirectory: "." }, launch: { command: process.execPath, arguments: ["main.js"] } });
+  }
+
+  function recentCaptures() {
+    return ["a.png", "b.png"];
+  }
+
+  export const options = {
+    icon: "tray.ico",
+    tooltip: "My app",
+    guid: "7d1c5a52-3f1b-4a63-9f5e-2f4d6b0c8a11",
+    onactivate: openApp,
+    resolve: resolveMenu
+  };
+</script>
+
+<script lang="ts">
+  import { TrayMenu, TrayMenuItem, TrayMenuSubmenu } from "winui-svelte/tray/menu/svelte";
+</script>
+
+<TrayMenu>
+  <TrayMenuItem id="open" label="Open" isRequired onselect={openApp} />
+  <TrayMenuSubmenu id="recent" label="Recent" emptyLabel="Nothing yet">
+    {#each recentCaptures() as name, iCapture (name)}
+      <TrayMenuItem id={`recent.${iCapture}`} label={name} />
+    {/each}
+  </TrayMenuSubmenu>
+  {#if isAutostart}
+    <TrayMenuItem id="delay" label="Delay at sign-in" />
+  {/if}
+</TrayMenu>
+```
+
+- `<script module>` holds `export const options = { ... }`, the options of
+  `defineTray` except `menu` (the markup is the menu); the build reads `icon`,
+  `tooltip` and `guid` from its literals as it does for `tray.ts`, and
+  everything `options` uses (functions, imports) lives in the same script,
+  because Svelte keeps a module script apart from the instance script; a
+  `satisfies` on the object is read through
+- The menu is read each time it opens, like the dynamic values of the model, so
+  a plain `let` and a plain function are always current; there is no `$state`,
+  `$derived`, `$effect`, `$props`, `$bindable`, `$inspect` or `$host` (the build
+  refuses them, since nothing would re-run)
+- Supported: `TrayMenu` (once, the root, no attributes), `TrayMenuItem` (a
+  command, or `kind="check"` or `kind="radio"`), `TrayMenuSubmenu`,
+  `TrayMenuSeparator` and `TrayMenuHeader`, imported by name; attributes as
+  `label="text"`, `label="x {y}"`, `label={expression}`, `{shorthand}`, a bare
+  boolean (`isRequired`), `{...spread}` and `onselect={handler}`; `{#if}`,
+  `{:else if}` and `{:else}`; `{#each list as item, index (key)}` over an array
+  (the key is not used, the `id` is the identity); `{@const}`; the children of
+  a submenu become its `items` function
+- Refused with an error that names the file, the line and the construct:
+  components of your own, other elements, `{#await}`, `{#key}`, `{#snippet}`,
+  `{@render}`, `{@html}`, `{@debug}`, `bind:`, `use:`, `on:`, `class:`,
+  `style:`, `let:`, transitions, `animate:`, `{@attach}`, `<svelte:*>`, text
+  between the lines, `{:else}` of an `{#each}` (give the submenu an
+  `emptyLabel`), a `<style>` block and importing a `.svelte` file
+- Each line becomes an object literal and `menu` the function that returns
+  them: `{#if}` spreads a conditional array, `{#each}` spreads `flatMap`, so
+  `defineTray` receives `menu: () => [ ... ]` (a function is accepted wherever
+  an array is, by `createStandaloneTray` too)
+- `svelte-check` and the editor check the markup against the props of the
+  components, so a wrong attribute or value is an error there; the build
+  checks nothing, as for any `.svelte` file
+- A `tray.svelte` built to `tray.js` is within a few dozen bytes of the same
+  tray written in `tray.ts` (`scripts/pack/tray-svelte-entrypoint.test.ts`)
+
+The working example is `examples/tray-entrypoint-svelte`
+
 ### Notice with no app (`winui-svelte/notice`)
 
 `showNotice` shows a message box before there is a window or an app: the
@@ -2952,7 +3731,8 @@ const isConfirmed = pressed === NoticeButton.YES;
 ### Taskbar button (`winui-svelte/window/taskbar`)
 
 `handle.taskbar` is the window's button on the taskbar: a progress bar, an
-overlay icon and flashing, over `ITaskbarList3` and `FlashWindowEx`
+overlay icon, flashing and the thumbnail's tooltip and clip, over
+`ITaskbarList3` and `FlashWindowEx`
 No package identity is needed; call it on the UI thread
 The shell calls need the real desktop shell, so a window on a desktop of its
 own gets `E_NOTIMPL`; a window that has no taskbar button (a background or
@@ -2978,6 +3758,15 @@ handle.taskbar.flash({ count: 2 });
 - `flash({ count, until })`: `until` is a `TaskbarFlashUntil` (`count`, the
   default, flashes `count` times, 3 by default; `foreground` until the window is
   brought forward; `stopped` until `stopFlashing()`)
+- `setThumbnailTooltip(text)`: the text above the window's thumbnail on hover
+  (259 characters at most, else a `RangeError`; empty shows the title again)
+- `setThumbnailClip({ x, y, width, height })`: shows only that part of the
+  window in the thumbnail, in pixels of the client area, inside it; `null`
+  shows all of it; whole numbers with a positive size, else a `TypeError`
+  `SetThumbnailClip` gets `E_NOTIMPL` on a desktop of its own, so only a fake
+  tests it
+- Thumbnail toolbar buttons are not offered: their click is a sent message
+  that Node cannot receive; use jump list tasks (`winui-svelte/app/jump-list`)
 - `createTaskbarButton(hwnd)` and `TaskbarButton` take a window handle
   (`appWindow.id.value`) directly; `taskbarBadgeBackend(button)` is the
   `fallback` for `installBadging`
@@ -3020,6 +3809,708 @@ handle.taskbar.flash({ count: 2 });
 The working example is `examples/services` (`test/services.test.ts` runs it in
 a real window; the dialogs themselves need a person and are not opened there)
 
+## ChromePermissions (`winui-svelte/chrome/permissions`)
+
+`chrome.permissions` for a native app, with Chrome's names and shapes:
+`getAll()`, `contains(permissions)`, `request(permissions)`,
+`remove(permissions)`, `onAdded` and `onRemoved` (a `ChromeEvent`), and
+`Permissions { permissions, origins }`
+Opt-in: nothing is bundled until an app imports it, importing does no work,
+and no global is installed
+
+```ts
+import { ChromePermissions } from "winui-svelte/chrome/permissions";
+
+const permissions = new ChromePermissions();
+permissions.onAdded.addListener(({ permissions: names }) => console.log(names));
+const isAllowed = await permissions.request({
+  permissions: ["geolocation"],
+  openSettings: true
+});
+```
+
+There is no per-site prompt in a native app; a permission is the OS consent
+the Permissions API already reports (`registerPermission` providers, so the
+Web APIs stay the single source of truth)
+The app holds a native permission when it asked for it and Windows allows it
+now; if either side takes it back, `contains` turns false
+The names the app asked for are saved in `chrome-permissions.json` in the
+app's data folder (`appDataFolder`, the folder `localStorage` uses), kept
+by an atomic write
+
+| Chrome name | Held when | Backed by |
+| --- | --- | --- |
+| `audioCapture` | allowed | `microphone` |
+| `videoCapture` | allowed | `camera` |
+| `geolocation` | allowed | `geolocation` |
+| `notifications` | allowed | `notifications` |
+| `clipboardRead`, `clipboardWrite` | allowed | `clipboard-read`, `clipboard-write` |
+| `idle` | allowed | `idle-detection` |
+| `bluetooth` | allowed | `bluetooth` |
+| `gcm` | allowed | `push` |
+| `power` | allowed | `screen-wake-lock` |
+| `unlimitedStorage` | allowed | `persistent-storage` |
+| `activeTab`, `alarms`, `background`, `contextMenus`, `cookies`, `declarativeNetRequest`, `downloads`, `offscreen`, `scripting`, `storage`, `tabs`, `webRequest`, `windows` | always | nothing; no native meaning, and `remove` answers false |
+| any other name | never | `contains` and `request` reject with an `Error` |
+| origins (`<all_urls>` and match patterns) | always | nothing; a native app has no host permissions, a bad pattern rejects, `remove` answers false |
+
+- The table is data you can read: `NATIVE_PERMISSIONS` (a `Map` from a Chrome
+  name to the Web permissions behind it), `GRANTED_BY_DEFAULT` (a `Set` of the
+  always-held names) and `ALL_URLS` (`<all_urls>`)
+- `request` checks each missing native permission: a state of `prompt` calls
+  the provider's `request` (location shows the Windows prompt through
+  `Geolocator.RequestAccessAsync`); camera and microphone are asked by the
+  first device open, so they stay refused until Windows allows them
+- All requested permissions must be allowed, or `request` answers false and
+  saves nothing; `onAdded` fires with the new ones
+- WinUI-only extra: `openSettings: true` in the object of `request` opens the
+  Settings page with the switch (`ms-settings:privacy-webcam`,
+  `privacy-microphone`, `privacy-location`, `notifications`, `bluetooth`,
+  else `privacy`) when a permission stays refused; the answer is still false
+- `remove` forgets the saved grant and fires `onRemoved`; Windows keeps its own
+  switch
+- Options of the constructor: `file`, `appName`, `location`, `environment`
+  and `openSettings`, the stand-ins for tests
+
+## ChromeContextMenus (`winui-svelte/chrome/context-menus`)
+
+`chrome.contextMenus` for a native app, with Chrome's names and shapes:
+`create(properties)` (answers the id), `update(id, properties)`,
+`remove(id)`, `removeAll()` and `onClicked` (a `ChromeEvent`); the item
+types `normal`, `checkbox`, `radio` and `separator`, and `title`, `id`,
+`checked`, `enabled`, `visible`, `contexts`, `parentId` and `onclick`
+Opt-in: nothing is bundled until an app imports it, importing does no work,
+and no global is installed
+
+The items live in one list and are drawn by the tray menu model
+(`winui-svelte/tray/menu`), not by a second menu implementation:
+`menu(surface)` answers the lines for `TrayIcon` (`menu={...}`) or for a
+window's context flyout, in the same `MenuItem` shape
+The array is the same object each time and is rewritten in place when an item
+changes, so a menu that reads it when it opens shows the current items
+
+```ts
+import { ChromeContextMenus, ContextMenuSurface } from "winui-svelte/chrome/context-menus";
+
+const menus = new ChromeContextMenus();
+menus.create({ id: "pause", title: "Pause", type: "checkbox", contexts: ["action"] });
+menus.onClicked.addListener(({ menuItemId, checked }) => console.log(menuItemId, checked));
+const lines = menus.menu(ContextMenuSurface.TRAY);
+```
+
+| Context | Surface | Shown |
+| --- | --- | --- |
+| `action`, `browser_action`, `page_action` | `tray` | in the tray icon's menu |
+| `page` | `window` | in the context flyout of a window |
+| `all` | both | in both |
+| `frame`, `selection`, `link`, `editable`, `image`, `video`, `audio`, `launcher` | none | accepted and ignored; there is no page under a native menu |
+
+- `contexts` is `["page"]` when left out, as in Chrome
+- `documentUrlPatterns` and `targetUrlPatterns` are accepted and ignored
+- A radio belongs to the run of radios next to it among its siblings; a pick
+  ticks it and unticks the others of the run
+- A pick of a checkbox flips it; `onclick` runs first, then `onClicked`
+  fires with `menuItemId`, `parentMenuItemId`, `checked`, `wasChecked` and
+  `editable` (always false); there is no `pageUrl`, `selectionText` or tab
+- An item with children is drawn as a submenu; a hidden item leaves out its
+  children
+- `create` throws, and `update` and `remove` reject, with an `Error` for a
+  duplicate id, an unknown id or parent, a parent under the item, a missing
+  title, or a key Chrome does not know
+- Not mirrored: the callback arguments (use the promises), Chrome's grouping of
+  several top-level items under the extension's name, and the limit of six
+  top-level `action` items
+- Public exports: `ChromeContextMenus`, `ContextItemType`,
+  `ContextMenuSurface`, `ContextType`, `ChromeEvent`, and the types
+  `CreateProperties`, `OnClickData` and `UpdateProperties`
+
+## Downloads (`winui-svelte/downloads`)
+
+Downloads on the two APIs an app already knows: the web's `fetch` with the File
+System Access API, and `chrome.downloads`
+Opt-in: nothing is bundled until an app imports it, and importing does no work
+
+### Web layer: `fetchToFile`
+
+`fetchToFile` streams a URL into the file handle `showSaveFilePicker` gave
+(`installFileSystem` defines it), resumes with a Range request and marks the
+finished file as downloaded from the Internet
+
+```ts
+import { fetchToFile } from "winui-svelte/downloads";
+
+const handle = await showSaveFilePicker({ suggestedName: "setup.exe" });
+await fetchToFile({
+  url: "https://example.com/setup.exe",
+  handle,
+  onprogress: ({ loaded, total }) => console.log(loaded, total)
+});
+```
+
+- The body goes through `FileSystemWritableFileStream`; when it is whole the
+  file gets a `Zone.Identifier` alternate data stream with `ZoneId=3` and
+  `HostUrl` (the final address, without credentials), as a browser's download
+  would, so Explorer and SmartScreen warn before it runs; a volume with no
+  streams (FAT, a share) stays unmarked
+- A failed or cancelled (`signal`) read keeps the bytes that arrived;
+  `resume: true` sends `Range: bytes=<size of the file>-` and appends to it
+  when the server answers 206 with the matching `Content-Range`; a server that
+  ignores the range (200) or refuses it (416) makes the download start over
+- `onprogress({ loaded, total })` runs after every chunk; `total` is undefined
+  when the server sends no length or compresses the body
+- A non-2xx answer throws `DownloadError` with the `status`; `headers`,
+  `method` and `body` shape the request and `fetch` stands in for the global
+  one (the tests do)
+- `requestDownload` and `streamToFile` are the two halves of `fetchToFile`, for
+  an app that decides the file after the headers arrive;
+  `markOfTheWeb({ path, hostUrl })` marks a file saved another way and
+  `zoneIdentifierText(hostUrl)` is the stream's text
+
+### Chrome layer: `Downloads`
+
+`Downloads` is `chrome.downloads` with the same names and shapes; where Chrome
+takes a callback, a method returns a promise
+
+```ts
+import { Downloads } from "winui-svelte/downloads";
+
+const downloads = new Downloads();
+downloads.onChanged.addListener(({ id, state }) => {
+  if (state?.current === "complete") {
+    console.log(`download ${id} is done`);
+  }
+});
+const id = await downloads.download({
+  url: "https://example.com/setup.exe",
+  filename: "installers/setup.exe",
+  conflictAction: "uniquify",
+  taskbar: handle.taskbar
+});
+await downloads.pause(id);
+await downloads.resume(id);
+const [item] = await downloads.search({ id });
+```
+
+- `download({ url, filename, saveAs, conflictAction, headers, method, body })`
+  returns the id once the download has started; the options are checked with
+  zod, so a bad `url`, `method` or an unknown key rejects; `filename` is
+  relative to the downloads folder (`directory` of the constructor, the user's
+  Downloads folder by default) and may not leave it
+- The file name is `filename`, else the server's `Content-Disposition`, else
+  the last part of the address; `conflictAction` is `uniquify` (the default,
+  `name (1).ext`), `overwrite` or `prompt`; `saveAs` and `prompt` ask with the
+  global `showSaveFilePicker` (or `pickSaveFile` of the constructor)
+- The bytes arrive in the file's name plus `.part`, renamed when whole, with
+  the Mark of the Web
+- `pause(id)` keeps the bytes (`paused: true`, `canResume: true`) and
+  `resume(id)` asks for the rest with a Range request; a dropped connection
+  ends `interrupted` with `NETWORK_FAILED` and can resume too; `cancel(id)`
+  deletes the bytes and ends `interrupted` with `USER_CANCELED`
+- `search(query)` takes Chrome's `DownloadQuery` (`query` terms, with a leading
+  `-` to exclude, `filenameRegex`, `urlRegex`, `startedBefore` and the other
+  time bounds, `totalBytesGreater`, `limit`, `orderBy` and every field as an
+  exact match); `erase(query)` removes the ones that are not running from the
+  list and returns their ids, the files stay; `removeFile(id)` deletes the file
+- `show(id)` and `showDefaultFolder()` open Explorer through `revealInExplorer`
+- `onCreated` gets the `DownloadItem`, `onChanged` a `DownloadDelta` with only
+  what changed (`state`, `paused`, `bytesReceived`, `totalBytes`, `error`,
+  `canResume`, `filename`, and so on) and `onErased` the id; they have
+  `addListener`, `removeListener`, `hasListener` and `hasListeners`
+- The closed sets are `DownloadState` (`in_progress`, `interrupted`,
+  `complete`), `FilenameConflictAction`, `HttpMethod` and `InterruptReason`,
+  and `ChromeEvent` is the class of the three events
+- `DownloadItem.totalBytes` and `fileSize` are -1 while unknown, as in Chrome;
+  the `error` values are `InterruptReason`'s, and an HTTP status maps to
+  `SERVER_UNAUTHORIZED`, `SERVER_FORBIDDEN`, `SERVER_BAD_CONTENT` or
+  `SERVER_FAILED`
+- `taskbar` is the one extra member of the options object: `handle.taskbar`
+  shows a bar that fills as the download goes (a marquee when the size is
+  unknown), yellow while paused, removed when it ends and red when it fails
+- Not mirrored: `open`, `getFileIcon`, `acceptDanger`, `setShelfEnabled`,
+  `onDeterminingFilename` and the danger types, a download here is always safe
+- `src/downloads/fetch-to-file.test.ts` and `chrome-downloads.test.ts` run
+  against a local HTTP server with Range support
+
+## Chrome storage (`winui-svelte/chrome/storage`)
+
+`chrome.storage` with the same areas, names and shapes; where Chrome takes a
+callback, a method returns a promise
+Opt-in: nothing is bundled until an app imports it, and importing does no work
+
+```ts
+import { ChromeStorage } from "winui-svelte/chrome/storage";
+
+const storage = new ChromeStorage();
+storage.onChanged.addListener((changes, areaName) => {
+  console.log(areaName, changes);
+});
+await storage.local.set({ theme: "dark", volume: 0.8 });
+const { theme } = await storage.local.get({ theme: "light" });
+await storage.session.set({ token: "abc" });
+await storage.local.remove(["volume"]);
+const bytes = await storage.local.getBytesInUse();
+```
+
+- Areas: `local`, `sync`, `session` and `managed`, each a `StorageArea` with
+  `get`, `getKeys`, `getBytesInUse`, `set`, `remove`, `clear`,
+  `setAccessLevel` and `onChanged`; `ChromeStorage.onChanged` fires for every
+  area with `(changes, areaName)`
+- `get(keys)` takes a key, an array of keys, an object of defaults, or null or
+  nothing for every item; arguments are checked with zod and a wrong one
+  rejects
+- Values are JSON, as in Chrome: a value JSON cannot hold (a function,
+  `undefined`) is left out, `NaN` becomes `null` and a `Date` becomes its
+  string; the stored files are checked with zod and a corrupt one reads as
+  empty
+- `local` is a JSON file in the app's local data folder, next to
+  `localStorage` (`chrome-storage-local.json`, written atomically after every
+  change); `session` is in memory and ends with the process; the file is read
+  on the first call to the area
+- `sync` is a local fallback: Windows has no sync service an unpackaged app
+  can use (roaming settings are deprecated), so `chrome-storage-sync.json`
+  lives beside the local file and values never reach another PC; Chrome's
+  `sync` limits apply (`QUOTA_BYTES` 102400, `QUOTA_BYTES_PER_ITEM` 8192,
+  `MAX_ITEMS` 512) so code meets the same errors; the write-rate constants are
+  published and not enforced
+- `managed` is read-only and always empty: `set`, `remove` and `clear` reject
+  with `This is a read-only store.`, and `get` answers the defaults
+- `QUOTA_BYTES` is 10485760 for `local` and `session`, and a write that would
+  pass a quota rejects and stores nothing; `getBytesInUse` counts each key's
+  length plus its JSON text, as Chrome does
+- `onChanged` gets `{ key: { oldValue, newValue } }` only for keys that
+  changed (`oldValue` is missing for a new key, `newValue` for a removed one);
+  a write that changes nothing fires nothing
+- `setAccessLevel({ accessLevel })` takes `AccessLevel`'s values and keeps
+  them; every context of a native app is trusted, so it changes nothing
+- A change made by another process is not seen, and `ChromeStorage` takes
+  `appName`, `environment`, `localFile` and `syncFile` (the tests give an
+  in-memory file); the closed sets are `StorageAreaName` and `AccessLevel`
+- `LOCAL_QUOTA`, `SESSION_QUOTA` and `SYNC_QUOTA` hold the numbers each area
+  publishes, for code that wants them without making a `ChromeStorage`
+- `src/chrome/storage/chrome-storage.test.ts` runs against an in-memory file
+
+## Chrome runtime (`winui-svelte/chrome/runtime`)
+
+`chrome.runtime` for a native app: the manifest, messages and ports between the
+app's own contexts, native messaging hosts, and the install and exit events
+Opt-in: nothing is bundled until an app imports it, importing does no work, and
+no global `chrome` is installed; make one `Runtime` in each context that wants
+one
+
+```ts
+import { Runtime } from "winui-svelte/chrome/runtime";
+
+const runtime = new Runtime();
+runtime.addLink(transport);
+runtime.onMessage.addListener((message, sender, sendResponse) => {
+  sendResponse({ echo: message });
+});
+const answer = await runtime.sendMessage({ hello: "world" });
+```
+
+- Where Chrome sets `chrome.runtime.lastError`, a promise rejects or a `Port`
+  has an `error`; there is no `lastError`
+- `getManifest()` gives `{ manifest_version: 3, name, version, description }`
+  from the package identity when the app has one, else from the nearest
+  `package.json` above the entry script; `id` is the package family name, or
+  the `package.json` name; `getURL(path)` is `ms-appx:///path` in a package and
+  a `file:` URL under the folder of `package.json` otherwise;
+  `getPlatformInfo()` is `{ os: "win", arch }` with Chrome's architecture names
+- Contexts are joined by `addLink(transport)`, with any transport of
+  `winui-svelte/state` (a worker's message port, stdio, memory); the call
+  returns how to leave; messages are `defineMessaging` requests, so framing,
+  timeouts (`timeoutMilliseconds`) and a closed link are the messaging layer's
+  own, and every frame is checked with zod
+- `sendMessage(message)` reaches every other linked context and resolves with
+  the first answer; a listener answers with `sendResponse`, by returning `true`
+  and calling it later, or by returning a promise; it resolves `undefined` when
+  listeners heard it and none answered, and rejects with Chrome's own "Receiving end does not exist" error when no
+  context is linked or none listens; a listener that throws or rejects rejects the sender
+- `connect({ name })` opens a `Port` to every other linked context, which hears
+  it in `onConnect`; `Port` has `postMessage`, `onMessage`, `onDisconnect`,
+  `disconnect()`, `name` and `sender`; a port ends when the link closes, and
+  `error` says why when something failed
+- `connectNative(application)` and `sendNativeMessage({ application, message })`
+  start a registered host and speak the native messaging protocol on its stdio
+  (four bytes of length, then JSON; a host's message is limited to 1 MiB)
+- A host is registered as in Chrome: a key
+  `Software\winui-svelte\NativeMessagingHosts\<name>` below
+  `HKEY_CURRENT_USER` whose default value is the path of the manifest (`name`,
+  `path`, `type: "stdio"`, `allowed_origins`); the host gets the app's origin,
+  `winui-svelte://<id>/`, as its first argument, and an `allowed_origins` that
+  omits it refuses the host; a host is an executable, not a script;
+  `resolveHost`, `registry` and `spawnHost` stand in for the lookup and the
+  start in a test
+- `onInstalled` fires from `detectInstalled()`, which an app calls once at
+  start: `{ reason: "install" }` on a first run, `{ reason: "update",
+  previousVersion }` when the version changed, nothing when it is the same; the
+  last version is kept in `%LOCALAPPDATA%\winui-svelte\runtime\<id>.json`, or
+  in the `versionStore` you give
+- `onStartup` is the `onStartup` of `winui-svelte/app/schedule`, fired by
+  `startActivation` for a `startup` activation (see `launchAtLogin`), not a
+  second source
+- `onSuspend` fires when the process exits, the only suspend a desktop app
+  has; `suspendSource` changes what it listens to; `dispose()` stops it and
+  closes the links
+- `reload()` is `relaunch` of `winui-svelte/app`
+- The protocol's pieces are exported for a host written in Node:
+  `encodeNativeMessage(message)`, `NativeMessageDecoder` (`push(chunk)` returns
+  the messages a chunk completed), `NativeMessageError`, `MAX_HOST_MESSAGE_BYTES`
+  and `NATIVE_HOST_REGISTRY_KEY`, the registry key below `HKEY_CURRENT_USER`
+  that holds the hosts
+- Not mirrored: `onMessageExternal`, `onConnectExternal`, `onSuspendCanceled`,
+  `onUpdateAvailable`, `requestUpdateCheck`, `restart`, `setUninstallURL`,
+  `openOptionsPage`, `getContexts`, `getPackageDirectoryEntry`
+- The single-instance pipe stays the way a second copy of the app reaches the
+  first (`startActivation`); contexts of one copy talk over their transports
+- `src/chrome/runtime/runtime.test.ts` runs it over in-memory links and a child
+  process that echoes in the native messaging protocol
+
+## Chrome notifications (`winui-svelte/chrome/notifications`)
+
+`chrome.notifications` for a native app, with Chrome's names and shapes; where
+Chrome takes a callback, a method returns a promise
+It delegates to the web `Notification` (`winui-svelte/web-apis/notification`),
+so there is one notification pipeline: the same permission, the same Windows
+app notifications and the same progress bar
+Opt-in: nothing is bundled until an app imports it, importing does no work, and
+no global is installed
+`installNotification()` must have run, as for the web `Notification`
+
+```ts
+import { ChromeNotifications } from "winui-svelte/chrome/notifications";
+
+const notifications = new ChromeNotifications();
+notifications.onButtonClicked.addListener((id, index) => console.log(id, index));
+await notifications.create("sync", {
+  type: "progress",
+  title: "Syncing",
+  message: "Uploading photos",
+  progress: 10,
+  buttons: [{ title: "Pause" }]
+});
+await notifications.update("sync", { progress: 60 });
+```
+
+- Exports: `ChromeNotifications`, `ChromeEvent`, `NotificationTemplateType`
+  (`basic`, `image`, `list`, `progress`) and `NotificationPermissionLevel`
+  (`granted`, `denied`), and the option types
+- `create(id, options)` resolves with the id (made up for a missing or empty
+  one); the same id replaces the notification that is up, without `onClosed`
+  The first call asks Windows for the permission and rejects with an `Error`
+  when it is refused
+- `type`, `title` and `message` are required, and so is `imageUrl` for `image`,
+  `items` for `list` and `progress` (0 to 100) for `progress`; `iconUrl` is
+  optional, since an unpackaged app may have none; options are checked with a
+  schema and a bad one rejects with an `Error`
+- `update(id, options)` merges into the notification and answers false when
+  there is none; a change of `progress` alone moves the bar in place
+  (`Notification.update`), anything else shows it again under its id
+- `clear(id)` removes it and answers false when there is none; `getAll()`
+  answers an object with each id as a key and `true` as the value, for the
+  notifications this run holds
+- `getPermissionLevel()` reads `Notification.permission`: `granted`, else
+  `denied` (including "not asked yet", which the first `create` settles)
+- `onClicked(id)`, `onButtonClicked(id, buttonIndex)` and `onClosed(id, byUser)`
+  are `ChromeEvent`s; Windows removes a clicked toast, so a click is followed
+  by `onClosed(id, true)`, `clear` fires `onClosed(id, false)`, and a swipe away
+  is not reported
+- `isClickable: false` silences `onClicked` for the body, not the buttons
+- Mapping: `message` is the body, `list` adds one `title: message` line per
+  item, `image` uses `imageUrl`, `contextMessage` is the attribution,
+  `eventTime` the timestamp, `buttons` (at most 2) become actions named by
+  their index, `priority` below 0 is silent and 2 requires interaction, and
+  `requireInteraction` and `silent` pass through
+- Not mirrored: `onPermissionLevelChanged` and `onShowSettings`
+- `src/chrome/notifications/chrome-notifications.test.ts` runs the web
+  `Notification` over a stand-in for the Windows App SDK; no toast is shown
+
+## Chrome commands (`winui-svelte/chrome/commands`)
+
+`chrome.commands` for a native app: the manifest's `commands` key as global
+hotkeys, over `registerHotkey` of `winui-svelte/app/hotkeys`
+Opt-in: nothing is bundled until an app imports it, importing does no work, and
+no global `chrome` is installed
+
+```ts
+import { ChromeCommands } from "winui-svelte/chrome/commands";
+
+const commands = new ChromeCommands({
+  commands: {
+    toggle: {
+      suggested_key: { default: "Ctrl+Shift+Y", mac: "Command+Shift+Y" },
+      description: "Toggle the panel"
+    }
+  }
+});
+commands.onCommand.addListener(name => console.log(name));
+const failures = commands.start();
+const all = await commands.getAll();
+```
+
+- `start()` registers every shortcut (call it on the UI thread, where
+  `registerHotkey` belongs) and returns the commands whose shortcut was
+  refused, as `{ name, error }`; a clash with another app leaves that command
+  unassigned, so its `getAll` shortcut is empty, as in Chrome; `stop()` gives
+  the shortcuts back
+- `getAll()` resolves with `{ name, description, shortcut }` for each command
+  in the manifest's order, the shortcut spelled `"Ctrl+Shift+Y"`
+- `suggested_key` is a string or one per platform; `windows` then `default`
+  is used, and `mac`, `linux` and `chromeos` are ignored
+- `Ctrl`, `Alt` and `Shift` are as in Chrome; `Command` and `MacCtrl` mean
+  Ctrl; keys are `A` to `Z`, `0` to `9`, `F1` to `F12`, `Comma`, `Period`,
+  `Home`, `End`, `PageUp`, `PageDown`, `Space`, `Insert`, `Delete`, `Up`,
+  `Down`, `Left`, `Right` and the four media keys; `parseShortcut(text)`
+  reads one into the `HotkeyChord` and the display spelling, and throws for
+  anything else
+- A bad manifest (a shortcut Chrome would not take, or a wrong shape, checked
+  with zod) throws from the constructor
+- Chrome keeps most shortcuts inside the browser; a native app has no such
+  scope, so every shortcut with a key is system-wide and `global` changes
+  nothing
+- `_execute_action` (and `_execute_browser_action`, `_execute_page_action`)
+  call `onExecuteAction` when you give it, as Chrome treats them as a click on
+  the action (pass `() => action.click()` of `winui-svelte/chrome/action`),
+  and fire `onCommand` otherwise
+- `onCommand` is a `ChromeEvent` and is called with the name only, there is no
+  tab; `register` stands in for `registerHotkey` in a test
+- Not mirrored: `onChanged`, and the shortcut customisation page
+- `src/chrome/commands/chrome-commands.test.ts` runs it over a fake registrar,
+  so no real hotkey is registered
+
+## Chrome i18n (`winui-svelte/chrome/i18n`)
+
+`chrome.i18n` for a native app: `getMessage` is synchronous, over the
+standard `_locales/<locale>/messages.json` files, so an unmodified
+extension's locale folder works
+Opt-in: nothing is bundled until an app imports it, importing does no work, and
+no global `chrome` is installed
+
+```ts
+import { ChromeI18n, installLanguageDefaults } from "winui-svelte/chrome/i18n";
+
+const i18n = new ChromeI18n();
+i18n.getMessage("greeting", ["Ann", "3"]);
+installLanguageDefaults(i18n);
+```
+
+- `getMessage(name, substitutions)` takes a string or up to nine strings;
+  `$1` to `$9` are the substitutions, `$NAME$` is the content of the
+  message's `placeholders` entry of that name (which may hold `$1`), and `$$`
+  is a dollar sign; names are matched without case; an unknown name gives an
+  empty string, as in Chrome
+- Lookup is per message: the exact locale (`pt-BR` is the folder `pt_BR`),
+  then its language (`pt`), then the `default_locale` of `manifest.json`
+  beside the folder; `localesFolder`, `root`, `defaultLocale`, `uiLanguage` and
+  `acceptLanguages` override the defaults (the app's root, `_locales` in it,
+  the system language)
+- The predefined messages are `@@extension_id`, `@@ui_locale` (`en_US`),
+  `@@bidi_dir`, `@@bidi_reversed_dir`, `@@bidi_start_edge` and
+  `@@bidi_end_edge`
+- `getUILanguage()` is a BCP 47 tag; `getAcceptLanguages()` resolves with the
+  list; `detectLanguage(text)` tells scripts apart (Arabic, Hebrew, Cyrillic,
+  Greek, Thai, Devanagari, Hangul, kana and Han) and answers `und` for
+  Latin-script text, where Chrome uses a trained model
+- Every `messages.json` is checked with zod; a malformed one throws from
+  `getMessage`
+- `installLanguageDefaults(source)` makes `navigator.language`,
+  `navigator.languages`, the default locale of the `Intl` formats and of
+  `toLocaleString` (and its date and time forms) follow the same source, so
+  they agree with `chrome.i18n`; a locale a caller passes still wins; it
+  returns the function that undoes it
+- `src/chrome/i18n/chrome-i18n.test.ts` runs it over in-memory files
+
+## Chrome global (`winui-svelte/chrome/install`)
+
+`installChromeApis` defines `globalThis.chrome` for code written for a Chrome
+extension
+Opt-in: importing does no work, and the global holds exactly the namespaces the
+app passes, so the bundle holds only what the app imported to make them
+
+```ts
+import { installChromeApis } from "winui-svelte/chrome/install";
+import { ChromeI18n } from "winui-svelte/chrome/i18n";
+import { ChromeStorage } from "winui-svelte/chrome/storage";
+import * as alarms from "winui-svelte/app/schedule";
+
+const uninstall = installChromeApis({
+  storage: new ChromeStorage(),
+  i18n: new ChromeI18n(),
+  alarms
+});
+await chrome.storage.local.set({ theme: "dark" });
+```
+
+- `ChromeGlobal` is the options object and the type of `globalThis.chrome`; its
+  members are `storage`, `runtime`, `permissions`, `contextMenus`, `commands`,
+  `action`, `notifications`, `i18n`, `alarms`, `downloads`, `system` and `windows`, each optional,
+  each an instance (or, for `alarms`, the `ChromeAlarms` calls and events of
+  `winui-svelte/app/schedule`); the object is open to more namespaces as they
+  are mirrored
+- The package declares no global type; to type `chrome` in your app, declare
+  `var chrome: ChromeGlobal` in your own `declare global`
+- A `chrome` object that is already there keeps its other members; the
+  returned function puts the previous one back
+- It does not call `installLanguageDefaults`; do that where you want
+  `navigator.language` and `Intl` to follow `chrome.i18n`
+- `src/chrome/install.test.ts` covers it
+
+## Chrome action (`winui-svelte/chrome/action`)
+
+`chrome.action` for a native app, over the tray icon (`winui-svelte/tray`)
+Opt-in: nothing is bundled until an app imports it, importing does no work, and
+no global `chrome` is installed
+
+```ts
+import { createChromeAction } from "winui-svelte/chrome/action";
+
+const { action, tray } = createChromeAction({
+  icon: "app.ico",
+  title: "Inbox",
+  guid: "0b3c0a53-2a8f-4a5e-9d57-1c2f7c1a9f10"
+});
+action.onClicked.addListener(() => console.log("clicked"));
+await action.setBadgeText({ text: "3" });
+```
+
+- `createChromeAction(options)` takes the options of `createTrayIcon` (except
+  `onclick`) and `title`, makes the tray icon and returns `{ action, tray }`;
+  call it on the UI thread; the left click is `onClicked`, the other gestures
+  go to the tray as given; `createTray` stands in for `createTrayIcon` in a test
+- `new ChromeAction({ title, tray })` is the same without making the tray: give
+  the tray's `onclick` to `action.click()`, then `attach(tray)` (a tray from
+  `defineTray` fits), through the `ActionTray` shape
+- `setTitle({ title })` and `getTitle()` are the tooltip, kept to what the shell
+  holds (127 characters)
+- `setIcon({ path })` swaps the icon file; `path` is a string or
+  `{ forLightTaskbar, forDarkTaskbar }`; Chrome's `imageData` and size maps
+  are rejected
+- `setBadgeText({ text })` and `getBadgeText()`: the tray cannot paint on an
+  icon (icons are files loaded by path, and drawing needs a new icon file on
+  every change), so the badge is a tooltip suffix, `"Inbox (3)"`; empty text
+  clears it
+- `setBadgeBackgroundColor({ color })` and `getBadgeBackgroundColor()` keep the
+  color (four channels, or `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`; Chrome's
+  red until set) and nothing draws it
+- `enable()`, `disable()` and `isEnabled()`: a disabled action still shows
+  (the tray cannot grey an icon) but a click on it is ignored
+- Every method returns a promise and rejects on a bad argument (zod); `tabId`
+  is accepted and ignored, there are no tabs, so everything is global
+- `onClicked` is a `ChromeEvent` and is called with no argument
+- Not mirrored: `setPopup`, `getPopup`, `openPopup`, `getUserSettings`,
+  `setBadgeTextColor`, `onUserSettingsChanged`
+- `src/chrome/action/chrome-action.test.ts` runs it over a fake tray
+
+## Chrome system (`winui-svelte/chrome/system`)
+
+`chrome.system` for a native app: `cpu`, `memory`, `storage` and `display`
+with Chrome's names and promises, over Node's `os` and the display areas
+that `winui-svelte/devices/display` and the web `screen` read
+Opt-in: nothing is bundled until an app imports it, importing does no work, and
+no global `chrome` is installed
+
+```ts
+import { createChromeSystem } from "winui-svelte/chrome/system";
+
+const system = createChromeSystem();
+const cpu = await system.cpu.getInfo();
+const memory = await system.memory.getInfo();
+const drives = await system.storage.getInfo();
+const displays = await system.display.getInfo();
+system.display.onDisplayChanged.addListener(() => console.log("changed"));
+```
+
+- `createChromeSystem(options)` returns `{ cpu, memory, storage, display }`
+  (`SystemCpu`, `SystemMemory`, `SystemStorage`, `SystemDisplay`); nothing is
+  read until a method is called; `backend` stands in for the machine in a
+  test, and `windowsSystemBackend()` is the default (`SystemBackend` is its
+  shape)
+- `cpu.getInfo()` resolves with `numOfProcessors`, `archName` (`x86-64`,
+  `arm64`, `x86-32`, `arm`), `modelName`, `features`, `processors` (the
+  `kernel`, `user`, `idle` and `total` milliseconds of each) and an empty
+  `temperatures`; `features` is `mmx`, `sse` and `sse2` on x64 and empty
+  elsewhere, as Node reports no others
+- `memory.getInfo()` resolves with `capacity` and `availableCapacity` in bytes
+- `storage.getInfo()` resolves with `{ id, name, type, capacity }` for each
+  drive letter, `type` one of `StorageUnitType` (`fixed`, `removable`,
+  `unknown`), read with `GetDriveTypeW`
+- `storage.onAttached` and `storage.onDetached` are not mirrored: Windows
+  tells an app about a drive coming or going only through a hidden window's
+  `WM_DEVICECHANGE` or a `DeviceWatcher` that needs a package identity; call
+  `getInfo` again
+- `display.getInfo(flags)` resolves with one record per display area, the
+  primary first: `id`, `name` (`Display 1` and so on), `isPrimary`,
+  `isEnabled`, `dpiX`, `dpiY` (the system scale times 96), `bounds` and
+  `workArea` as `{ left, top, width, height }` in screen pixels;
+  `mirroringSourceId` is empty and `rotation` 0, as Windows tells an app
+  neither; `singleUnified` is accepted and ignored; a flag of the wrong
+  type rejects (zod)
+- `display.onDisplayChanged` is a `ChromeEvent` called with no argument; the
+  display watcher runs only while a listener is added
+- Not here on purpose: `chrome.idle` is the web `IdleDetector` and
+  `chrome.desktopCapture` the web `getDisplayMedia`, both already covered
+- `src/chrome/system/chrome-system.test.ts` runs it over a fake backend
+
+## Chrome windows (`winui-svelte/chrome/windows`)
+
+`chrome.windows` for the windows of a native app, over `WindowHandle`
+Opt-in: nothing is bundled until an app imports it, importing does no work, and
+no global `chrome` is installed
+
+```ts
+import { createWindow } from "winui-svelte/window";
+import { chromeWindowSurface, createChromeWindows, WindowState } from "winui-svelte/chrome/windows";
+
+const windows = createChromeWindows({
+  open: () => chromeWindowSurface(createWindow({ component: Panel, props: {} }).handle)
+});
+windows.track({
+  surface: chromeWindowSurface(mainHandle),
+  isCurrent: true
+});
+windows.onFocusChanged.addListener(windowId => console.log(windowId));
+const panel = await windows.create({ width: 400, height: 300 });
+await windows.update(panel.id, { state: WindowState.maximized });
+await windows.remove(panel.id);
+```
+
+- `createChromeWindows(options)` makes a `ChromeWindows`; make one and share
+  it, since the windows it knows and their ids live in it; no process-wide
+  list of windows exists, so the app hands it the windows
+- `track({ surface, isCurrent })` starts reporting a window, gives it an id
+  from 1 and fires `onCreated`; `chromeWindowSurface(handle)` makes a
+  `ChromeWindowSurface` of a `WindowHandle` (`bind:handle` on `<Window>`, or
+  the `handle` of what `createWindow` returns); a window leaves when it
+  closes, firing `onRemoved`
+- `create(createData)` calls the `open` option, which makes the content,
+  tracks what it returns and then applies `left`, `top`, `width`, `height`,
+  `state` and `focused`; without `open` it rejects; `url`, `tabId`, `type`,
+  `incognito` and `setSelfAsOpener` reach `open` and nothing else
+- `get(windowId)`, `getCurrent()`, `getLastFocused()` and `getAll()` resolve
+  with a `ChromeWindow`: `id`, `focused`, `top`, `left`, `width`, `height`,
+  `state`, `alwaysOnTop`, `incognito` (always false) and `type` (always
+  `normal`); places and sizes are in device pixels, as `AppWindow` has them;
+  `populate` and `windowTypes` are accepted and ignored, there are no tabs
+- `WINDOW_ID_CURRENT` (-2) names the window `track` marked current, else the
+  last focused; `WINDOW_ID_NONE` (-1) is what `onFocusChanged` reports when
+  focus leaves the app's windows
+- `update(windowId, updateInfo)` takes `left`, `top`, `width`, `height`,
+  `state` (`WindowState`: `normal`, `minimized`, `maximized`, `fullscreen`,
+  `locked-fullscreen`, the last as full screen), `focused` (true brings the
+  window forward; false changes nothing) and `drawAttention` (flashes the
+  taskbar button until the window is brought forward); as in Chrome a place
+  or size cannot go with a state other than `normal`, and `focused` cannot go
+  with `minimized`
+- `remove(windowId)` closes the window; `onRemoved` fires once it has closed,
+  so a close guard on the window keeps it
+- Every method returns a promise and rejects on a bad argument (zod) or an
+  unknown id; `WindowType` lists Chrome's types, and every window is `normal`
+- `onCreated`, `onRemoved`, `onFocusChanged` and `onBoundsChanged` are
+  `ChromeEvent`s; `onBoundsChanged` fires after a move or a resize
+- Not mirrored: `tabs` in a window, `create`'s `focused: false` and `incognito`
+  effects, and `onBoundsChanged`'s separate move and resize
+- `src/chrome/windows/chrome-windows.test.ts` runs it over fake windows
+
 ## Data transfer (`winui-svelte/data-transfer`)
 
 Drag and drop, file dialogs, the clipboard and the launcher, in the web's
@@ -3169,8 +4660,17 @@ picker code in `src/window/pickers.ts` is the one used)
 
 `clipboard.readText()`, `readHtml()`, `read({ formats })` (a `DataTransfer`),
 `types()`, `writeText(text)`, `write({ text, html, uri, files, bitmap, custom,
-shouldPersist })`, `clear()` and `onChange(callback)` (returns what stops it)
+shouldPersist, deferred })`, `clear()` and `onChange(callback)` (returns what
+stops it)
 `write` replaces the clipboard's whole content
+`deferred` maps a type to a provider (`() => Promise<string | NativeFile>`) that
+Windows runs when something pastes, through `DataPackage.SetDataProvider`; a
+source does the same for a drag with `event.dataTransfer.setDeferredData({
+type, provider })` in `dragstart`, and the data is made at the drop
+A type starting with `image/` is a picture, so its provider gives a `NativeFile`
+A provider that rejects leaves its format empty
+Windows runs a provider on the UI thread, and `shouldPersist` runs them at
+once, before the app exits
 
 ### Launcher and share
 
@@ -3207,6 +4707,242 @@ takes drops, through the handlers a real drop reaches, and resolves with the
 operation the control accepted (`0` when it refused); it sends no input, so an
 app can test its drop handling in a real window
 
+## Progress (`winui-svelte/progress`)
+
+One progress object for any long work: a download, a file read, a copy, an OCR
+pass; it is a promise, an `EventTarget` with the platform events, and
+reactive state, in one value
+Operations list themselves in an app-wide registry, so the taskbar button and
+the tray show them with no setup
+Opt-in: nothing is bundled until an app imports it, and importing does no work
+
+### Five call sites
+
+```svelte
+<script lang="ts">
+  import { Button, ProgressBar, TextBlock, Window } from "winui-svelte/components";
+  import { fetchToFile } from "winui-svelte/downloads";
+  import { TaskbarProgress } from "winui-svelte/progress";
+
+  // 1. A download with a bar: fetchToFile returns the operation at once
+  const download = fetchToFile({ url, handle });
+  download.then(size => console.log("saved", size));   // or: await download
+</script>
+
+<Window>
+  <TaskbarProgress />                           <!-- 4. the taskbar shows every running operation -->
+  <ProgressBar {...download.barProps} />        <!-- value, isIndeterminate, showPaused, showError -->
+  <TextBlock>{download.loaded} of {download.total ?? "?"}</TextBlock>
+  <Button onclick={() => download.cancel()}>Cancel</Button>
+</Window>
+```
+
+```ts
+// 2. Reading a file from disk, with progress and cancel
+const read = handle.read({ onprogress: event => console.log(event.loaded, event.total) });
+const file = await read;                 // a File, like getFile()
+read.cancel();                           // or abort the signal given in the options
+
+// 3. Any other long work: one call, no lifecycle code
+const copy = trackOperation({
+  label: "Copying photos",
+  group: "sync",
+  async run(operation) {
+    for await (const chunk of source) {
+      await write(chunk);
+      operation.update({ loaded: (written += chunk.byteLength), total });
+      operation.signal.throwIfAborted();
+    }
+  }
+});
+
+// 5. Retry: a failed fetchToFile continues where it stopped
+await fetchToFile({ url, handle, resume: true });
+```
+
+```svelte
+<!-- Tray menu, in tray.svelte markup -->
+<TrayMenu>
+  <TrayMenuProgress id="progress" />                  <!-- "setup.exe - 45%", hidden when idle -->
+  <TrayMenuOperations id="operations" label="Running" emptyLabel="Nothing running" />
+</TrayMenu>
+```
+
+`{...download.barProps}` spreads onto a `ProgressBar`; Svelte then cannot tell
+at build time whether a scoped class selector matches that bar, so write the
+five props out when the same component has a `<style>` rule for its siblings
+
+### Several windows and tray icons
+
+The registry is app-wide; what a taskbar button or a tray line shows is scoped
+by `group` (a name an operation is given) or by an operation or registry given
+as `of`
+A `<TaskbarProgress />` drives the taskbar button of the window it sits in;
+`window={handle}` picks another
+
+```svelte
+<script lang="ts">
+  const upload = trackOperation({ group: "uploads", run });
+  const download = fetchToFile({ url, handle, group: "downloads" });
+</script>
+
+<!-- Window A: its taskbar button shows the downloads only -->
+<Window bind:handle={windowA}>
+  <TaskbarProgress group="downloads" />
+</Window>
+
+<!-- Window B: its own button shows one upload; window A is not touched -->
+<Window>
+  <TaskbarProgress of={upload} />
+</Window>
+
+<!-- The main window drives window A from outside -->
+<TaskbarProgress window={windowA} group="downloads" />
+
+<!-- Two tray icons, each with its own menu and its own scope -->
+<TrayIcon>
+  <TrayMenu>
+    <TrayMenuProgress id="downloads" group="downloads" />
+  </TrayMenu>
+</TrayIcon>
+<TrayIcon>
+  <TrayMenu>
+    <TrayMenuOperations id="uploads" label="Uploads" group="uploads" />
+  </TrayMenu>
+</TrayIcon>
+```
+
+### `ProgressOperation`
+
+- It is `PromiseLike`: `await operation` gives the value passed to `complete`
+  and throws the reason of `fail` or `cancel` (an `AbortError` by default); an
+  operation nobody awaits raises no unhandled rejection
+- It is an `EventTarget` that fires `loadstart`, `progress`, `load`, `error`,
+  `abort` and `loadend` as `OperationProgressEvent` (`lengthComputable`,
+  `loaded`, `total`), in the order `XMLHttpRequest` and `FileReader` use, plus
+  `pause`, `resume` and `change`; `onprogress` and its kin work as properties
+  and as options
+- `value` (0 to 1), `loaded`, `total`, `state`, `isIndeterminate`,
+  `showPaused`, `showError`, `label` and `barProps` are reactive in markup and
+  in `$effect`, with the meaning `ProgressBar` gives them: a total that is
+  unknown is indeterminate
+- `$operation` works too: it has `subscribe` and so is a Svelte store
+- `signal` is an `AbortSignal` that aborts on `cancel()`; a `signal` given to
+  the constructor cancels the operation when it aborts
+- `start`, `update({ loaded, total })`, `pause`, `resume`, `complete(value)`
+  and `fail(reason)` are for the code doing the work; `resume` also retries an
+  errored operation (the other final states are final)
+- `ProgressState` is the closed set of states: `idle`, `running`, `paused`,
+  `complete`, `error`, `canceled`
+
+### Registry and scopes
+
+- `defaultProgressRegistry()` is the app-wide registry; an operation lists
+  itself there unless it gets `registry: otherRegistry` or `registry: false`
+- A finished or canceled operation leaves; a failed one stays so a red bar
+  is not lost, until `clearFailed()` or `remove(operation)`
+- `registry.where("sync")` or `registry.where(operation => ...)` is a scoped
+  registry that follows the first (call `dispose()` when done);
+  `<TaskbarProgress group>` and the tray components do this for you
+- `snapshot`, `value`, `count`, `state`, `isIndeterminate`, `showPaused` and
+  `showError` are the aggregate: the bar covers the operations that know their
+  total, and is indeterminate only when none does; `paused` when all that are
+  left are paused; `error` when only failed ones are left; `count` is the
+  number unfinished
+- `aggregateSnapshots` is that rule as a pure function
+
+### Taskbar and tray
+
+- `<TaskbarProgress of group window taskbar />` draws nothing and keeps the
+  taskbar button in step: a bar, a marquee when the total is unknown, paused
+  yellow, error red, gone when nothing is left; the shell is told only when the
+  bar moves by a thousandth
+- `bindTaskbarProgress({ source, taskbar })` is the same without markup (the
+  `taskbar` option of `Downloads.download` uses it); `taskbarOptionsOf` is the
+  mapping
+- `<TrayMenuProgress id of group />` is a command line with the text of
+  `progressText(snapshot)`, hidden while nothing runs; `onselect` is yours
+- `<TrayMenuOperations id label of group />` is a submenu with a line per
+  running operation; picking a line cancels it
+- `Downloads` gives each download an operation (`progress: registry` in its
+  options picks the registry, `group` in `download({ ... })` the group), and
+  `fetchToFile` returns one; `FileSystemFileHandle.read` is the extra (WinUI
+  only) that reads a file in 1 MiB chunks
+- `trackStream({ stream, operation })` passes a `ReadableStream` through and
+  reports the bytes; `trackOperation` is the whole lifecycle for any async work
+
+## Incremental loading (`winui-svelte/incremental`)
+
+A list that loads its next batch as the user scrolls near the end, for
+`ListView`, `GridView`, `ItemsRepeater`, `ItemsView` and `BreadcrumbBar`
+Opt-in: nothing is bundled until an app imports it, and importing does no work
+
+```svelte
+<script lang="ts">
+  import { ListView } from "winui-svelte/components";
+  import { createIncrementalSource, IncrementalStatus } from "winui-svelte/incremental";
+
+  const source = createIncrementalSource<Post>({
+    batchSize: 25,
+    load: ({ offset, count, signal }) => fetchPosts({ offset, count, signal })
+  });
+</script>
+
+<ListView incremental={source} item={postRow} items={source.items} key={post => post.id} />
+{#if source.state.status === IncrementalStatus.ERROR}
+  <button onclick={() => source.retry()}>Try again</button>
+{/if}
+```
+
+`createIncrementalSource({ load, batchSize, threshold, isLast })` (options:
+`IncrementalSourceOptions`) returns an `IncrementalSource`, generic over the item;
+`IncrementalLoading` is what a list asks of its `incremental` prop
+`load({ offset, count, signal })` resolves with the next items; fewer than
+`count` (or none) is the last batch, and `isLast({ batch, items })` decides when
+the size cannot (a server that sends a cursor)
+`batchSize` is 20 and `threshold` is 5 by default: the next batch loads when
+the control realizes an item within `threshold` of the end
+The source holds `items` and `state`, both reactive
+`state` is `{ status: "idle" | "loading" | "done" }` or
+`{ status: "error", error }`; `IncrementalStatus` names the four (also in
+`winui-svelte/enums`)
+
+- `loadMore()` loads now; while a load is in flight it returns that load's
+  promise, so a load never runs twice, and it never rejects
+- A failure is the `error` state and stays until `retry()`; the list does not
+  retry by itself
+- `cancel()` aborts the load in flight through its `AbortSignal` and drops its
+  result; `reset()` also clears the items, and a bound list loads the first
+  batch again; `dispose()` aborts for good
+- A list bound to a source starts it, so the first batch needs no call
+
+### The mechanism, and why
+
+WinUI's own is `ISupportIncrementalLoading` on the items source, which the
+list calls when it nears its end (`IncrementalLoadingTrigger`)
+winui-svelte does not use it: the items of these lists are a native vector of
+keys (see Items), and the interface belongs on the collection itself, which
+would have to be a JavaScript-made `IBindableVector`,
+`INotifyCollectionChanged` and `ISupportIncrementalLoading` returning an
+`IAsyncOperation`
+dynwinrt (0.1.0-preview.23) can make a COM object from a callback
+(`createComObject`), but nothing in this package has proved that WinUI binds it
+as an items source, and the same table would have to answer a bindable vector's
+every call, so it was not built
+Instead the control's own realization tells the source: ListView and GridView
+report each container's index through `ContainerContentChanging`, the repeaters
+through `ElementPrepared`, and the source loads when that index is within
+`threshold` of the end
+The report is made after the layout pass (a timer of zero, the furthest index of
+the pass), because a source that changes `state` during it changes the app's
+markup (a footer) while WinUI measures, which WinUI refuses
+`ScrollViewer.ChangeView` and a real scroll reach the source the same way
+(`test/incremental-list.test.ts`)
+
+A loading footer, an error row or a "no more" line is markup of the app, beside
+the list, from `source.state`; the list has no footer snippet of its own
+The example is `examples/incremental-list`
+
 ## Input events and focus (`winui-svelte/input`)
 
 The web's pointer, wheel, keyboard and focus events on any element, and focus
@@ -3361,6 +5097,7 @@ needs
 | `element.animate()`, `Animation`, `KeyframeEffect` | `winui-svelte/web-apis/animations` | web plus extras | none | done |
 | `ScrollTimeline`, `ViewTimeline`, `element.animate(keyframes, { timeline })` | `winui-svelte/scroll-timeline` | web | none | done |
 | `document.startViewTransition`, `ViewTransition`, `view-transition-name` | `winui-svelte/view-transitions` | web plus extras | none | done |
+| `alert`, `confirm`, `prompt` | `winui-svelte/dialogs` | web (as promises) plus extras | none | done |
 | `navigator.mediaDevices` (`getUserMedia`, `getDisplayMedia`, `enumerateDevices`), `MediaStream`, `MediaRecorder` | `winui-svelte/web-apis/media-devices` | web plus extras | none (a camera or microphone needs the Windows privacy switch on) | done |
 | `speechSynthesis`, `SpeechSynthesisUtterance`, `SpeechRecognition` (SSML, silences, scenario, phrases) | `winui-svelte/web-apis/speech` | web plus extras | none | done |
 | `navigator.mediaSession`, `MediaMetadata` | `winui-svelte/web-apis/media-session` | web plus extras | none | done |
@@ -3373,6 +5110,7 @@ needs
 | `navigator.credentials`, `PasswordCredential`, `PublicKeyCredential` (Windows Hello) | `winui-svelte/web-apis/credentials` | web plus extras | none | done |
 | `EyeDropper` | `winui-svelte/web-apis/eye-dropper` | web plus extras | none | done |
 | `FontFace`, `document.fonts` (font files of the app) | `winui-svelte/web-apis/fonts` | web plus extras | none | done |
+| `createImageBitmap`, `ImageBitmap`, `ImageDecoder`, canvas `toBlob`, `convertToBlob`, `toDataURL` (PNG, JPEG, GIF, BMP, TIFF) | `winui-svelte/web-apis/images` | web plus extras | none | done |
 | `navigator.contacts` (Contact Picker) | `winui-svelte/web-apis/contacts` | web plus extras | for most apps, package identity | done |
 
 Every row is built and tested; the timers (`setTimeout`, `setInterval`,
@@ -3406,7 +5144,9 @@ names the APIs register: `geolocation`, `accelerometer`, `screen-wake-lock`
 and so on) and `PermissionStateName` (`granted`, `denied`, `prompt`) are the
 spec's; an API registers its permission
 with `registerPermission({ name, provider })` and calls
-`announcePermissionChange(name)` when it moves, so open statuses fire `change`
+`announcePermissionChange(name)` when it moves, so open statuses fire `change`; a provider may add `request()` (the system
+prompt), which `requestPermission(name)` calls and `readPermission(name)` reads
+back, as `chrome.permissions` does
 
 ### The three kinds and the extras convention
 
@@ -3664,8 +5404,11 @@ Each is `install<Name>()` from its own subpath and takes an optional `backend`
   the always granted `clipboard-read` and `clipboard-write` permissions
   More than one item, or a type the clipboard cannot take, rejects with
   `NotAllowedError`
+  A type whose value is a promise (`new ClipboardItem({ "text/html": promise })`)
+  is delayed-rendered: `write` resolves at once and the promise is awaited
+  when something pastes
   Extras: `readContent({ formats })` (copied files in `files`, custom formats
-  as text), `writeContent({ files, custom, bitmap, shouldPersist })`,
+  as text), `writeContent({ files, custom, bitmap, deferred, shouldPersist })`,
   `formats()` and `history()` (Win+V, empty when history is off)
   `windowsClipboardBackend()` is the real backend, for a test to wrap
 - `winui-svelte/web-apis/share`: `installShare()` defines `navigator.share`
@@ -3904,6 +5647,73 @@ old element to the new one
   `:active-view-transition-type()` have no counterpart, and `types` is carried
   but read by nothing
 
+#### Dialogs (`winui-svelte/dialogs`)
+
+`installDialogs()` defines `alert`, `confirm` and `prompt` on the global scope
+over WinUI's `ContentDialog`
+
+```svelte
+<script lang="ts">
+  import { installDialogs, useDialogWindow } from "winui-svelte/dialogs";
+  import type { WindowHandle } from "winui-svelte/components";
+
+  installDialogs();
+  let handle = $state<WindowHandle>();
+
+  $effect(() => {
+    if (!handle) {
+      return;
+    }
+
+    return useDialogWindow(handle);
+  });
+
+  async function remove() {
+    const isSure = await confirm("Delete this file?");
+    if (isSure) {
+      await alert("Deleted");
+    }
+  }
+</script>
+```
+
+- Decision: they return promises, where the browser's block, because a
+  `ContentDialog` is asynchronous and the thread that would block is the one
+  that pumps the window, so a blocking version would freeze the dialog it
+  waits for; the web names are kept, so that a library written for a browser still calls them,
+  and the result is awaited: `await confirm(text)`. The other way (new names
+  and no globals) would make every such library need a patch; the cost of this
+  way is that `if (confirm(text))` is always true, because a promise is
+  truthy, and `lib.dom` still types the globals as synchronous; in your own
+  code call `showAlert`, `showConfirm` and `showPrompt` (the same functions,
+  typed as promises) and leave the globals to libraries
+- `alert(message)` resolves when the dialog closes, `confirm(message)`
+  resolves `true` for OK, `prompt(message, default)` resolves with the text or
+  `null` for Cancel, Escape or the close button; a message that is not a
+  string is shown as `String(message)`
+- `showDialog({ content, title, primaryButtonText, secondaryButtonText,
+  closeButtonText, defaultButton, input, signal })` is the WinUI form: three
+  buttons, the button Enter presses (`DialogButton`), a text box
+  (`{ value, placeholder, isMultiline }`) and an `AbortSignal` that closes the
+  dialog like Escape; it resolves with `{ result, text }`, where `result` is a
+  `DialogResult` (`primary`, `secondary` or `none`) and `text` is the box when
+  the primary button closed a dialog that had one
+- Which window: `useDialogWindow(handle)` takes the handle `bind:handle`
+  gives, for each window; the dialog opens in the one activated last, and the
+  function it returns stops following the window
+- One at a time: WinUI shows one `ContentDialog` per window, so a dialog asked
+  for while another is open waits, in order, in the same line the
+  `ContentDialog` components use; a dialog that fails does not hold the line,
+  and an aborted one that still waits is rejected with an `AbortError`
+- No window: `alert` and `confirm` show a message box (`showNotice`, with the
+  installed `title`), and `prompt` and `showDialog` reject with an
+  `InvalidStateError`, because a message box has no text box and no third
+  button
+- `installDialogs({ title, okText, cancelText })` sets the title and the
+  button texts (English by default; WinUI does not translate them)
+- Not covered: a dialog that blocks the caller, and the prompt of
+  `beforeunload`
+
 ### Media devices (`winui-svelte/web-apis/media-devices`)
 
 `installMediaDevices()` defines `navigator.mediaDevices` (`enumerateDevices`,
@@ -4250,6 +6060,42 @@ anywhere on the screen
 - `ScreenPicker` is the one interface the polling picker (`windowsScreenPicker`)
   and the tests implement
 
+#### Images (`winui-svelte/web-apis/images`)
+
+`installImageCodecs()` defines `createImageBitmap`, `ImageBitmap` and
+`ImageDecoder`, and adds `toBlob`, `convertToBlob` and `toDataURL` to
+`CanvasElement`; all of it runs on `Windows.Graphics.Imaging`, which needs no
+window and no package identity
+
+- `createImageBitmap(source, options?)` and `createImageBitmap(source, sx, sy,
+  sw, sh, options?)` take a `Blob`, `File` or `NativeFile` of an image file,
+  `ImageData`, an `ImageBitmap` or a canvas; `imageOrientation` (`from-image`,
+  `none`, `flipY`), `resizeWidth`, `resizeHeight` and `resizeQuality` work;
+  `premultiplyAlpha` and `colorSpaceConversion` are read and ignored (images are
+  color managed to sRGB); a file Windows cannot decode rejects with
+  `InvalidStateError`
+- `ImageBitmap` has `width`, `height` and `close()`; `drawImage` and
+  `createPattern` take it; extra: `toImageData()` (RGBA, not premultiplied)
+- `new ImageDecoder({ data, type })` takes bytes or a stream; `tracks` (an
+  `ImageTrackList` of one `ImageTrack`), `complete`, `completed`, `decode({ frameIndex })`, `reset()`,
+  `close()` and `ImageDecoder.isTypeSupported(type)`; `image` is an
+  `ImageBitmap`, not a `VideoFrame`, and `duration` is not reported; a GIF
+  frame is what the file stores, so an optimized GIF gives the changed area
+- Decoders: BMP, GIF, ICO, JPEG, PNG, TIFF, JPEG XR, and WebP, AVIF and HEIC
+  where Windows has the codec; `isTypeSupported` asks Windows' own list
+- Encoders: PNG, JPEG (`quality` 0 to 1 is `ImageQuality`, 0.92 by default;
+  transparency is drawn over black), GIF, BMP and TIFF; WebP has no Windows
+  encoder, so `toBlob`, `convertToBlob` and `toDataURLAsync` give a PNG for
+  `image/webp` and for any type Windows cannot write, as the platform does
+- `toDataURL(type, quality)` is synchronous and every Windows encoder is
+  asynchronous, so it always returns a PNG; extra: `toDataURLAsync(type,
+  quality)` encodes any type above
+- A canvas with no pixels gives `data:,`, `null` from `toBlob` and rejects
+  `convertToBlob`
+- `ImageCodec` is the one interface the Windows codec (`windowsImageCodec`)
+  and the tests implement; `ImageMimeType`, `ImageOrientation` and
+  `ResizeQuality` are in `winui-svelte/enums`
+
 #### Contacts (`winui-svelte/web-apis/contacts`)
 
 `installContacts()` defines `navigator.contacts` (a `ContactsManager`) with
@@ -4714,7 +6560,7 @@ and resets the context, as in a browser), `getContext("2d")` (the same
 `display` and any other property, with `setProperty`), `getBoundingClientRect()`,
 `clientWidth`, `clientHeight`, `offsetWidth`, `offsetHeight`, `addEventListener`,
 `removeEventListener` and `dispatchEvent`
-It has no document: there is no `ownerDocument` and no `toDataURL`, and
+It has no document: there is no `ownerDocument`, and `toDataURL` and `toBlob` exist only after `installImageCodecs()`, and
 `parentNode` is `null`
 
 Pointer events of the control reach the canvas as DOM events: `pointerdown`,
@@ -4785,8 +6631,8 @@ Not tried: the events need a real pointer, which a test must not inject
 | `globalCompositeOperation` of `multiply`, `screen`, `overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity` | Win2D blends an effect's inputs, not a shape with the canvas; the value is ignored |
 | `filter` | it is always `none`; use a Win2D effect on the image |
 | `letterSpacing`, `wordSpacing`, `fontKerning`, `fontStretch`, `fontVariantCaps`, `textRendering` | No Win2D equivalent set per draw call |
-| `drawImage` of an `HTMLImageElement`, `ImageBitmap`, `HTMLVideoElement` or `OffscreenCanvas` | There is no DOM; decode with `loadBitmap`, or draw another `CanvasElement` |
-| `toDataURL`, `toBlob`, `transferControlToOffscreen`, `captureStream` | No encoder is exposed on the canvas; `canvas.target.saveAsync` writes a PNG or JPEG file |
+| `drawImage` of an `HTMLImageElement`, `HTMLVideoElement` or `OffscreenCanvas` | There is no DOM; decode with `loadBitmap`, or draw another `CanvasElement`; an `ImageBitmap` from `winui-svelte/web-apis/images` draws |
+| `transferControlToOffscreen`, `captureStream` | There is no `OffscreenCanvas` or media stream; `toBlob`, `convertToBlob` and `toDataURL` come with `winui-svelte/web-apis/images` |
 | `getContext` of `webgl`, `webgl2`, `bitmaprenderer`; the `alpha`, `desynchronized` and `willReadFrequently` options | One 2D context, always with an alpha channel |
 | `scrollPathIntoView` | There is no element tree to scroll; the method is absent |
 | `requestAnimationFrame`, `devicePixelRatio`, `document`, `window` | Globals of a browser, defined by the opt-in `winui-svelte/web-apis/timing`, `/screen` and `/page`; `getComputedStyle` has no counterpart |
@@ -4800,6 +6646,78 @@ The working example is `examples/win2d` (`test/win2d.test.ts` runs it in a real
 window and checks the redraw; `src/win2d/win2d.test.ts` draws on a render
 target and checks the pixels)
 
+## UI Automation client (`winui-svelte/automation`)
+
+Read the exact text and headings of another window, instead of OCR; the
+counterpart of the Accessibility section, which provides automation to
+others, while this one consumes it; no web API reads another application's
+window, so this mirrors none; it is opt-in and bundles COM only when imported
+
+```ts
+import { createUiaWorker } from "winui-svelte/automation";
+
+const worker = createUiaWorker();
+const text = await worker.readText({
+  target: "foreground",
+  excludeProcessId: process.pid,
+  hardMilliseconds: 1500
+});
+// { title, blocks: [{ kind: "heading", level: 1, text }, ...], version, end }
+```
+
+`readText` runs in a worker thread in the multithreaded COM apartment; a target
+that hangs makes the call reject with `UiaTimeout` after `hardMilliseconds`,
+the worker is ended and the next call starts a new one (a blocked COM call
+cannot be cancelled); it resolves null when there is no window to read, the
+window is the excluded process's or an elevated one
+
+For the lower level, `withUiaClient` gives a client on the calling thread
+(call it from a thread that joined a COM apartment) and releases every COM
+pointer it made when the callback ends:
+
+```ts
+import { UiaControlType, withUiaClient } from "winui-svelte/automation";
+
+const lines = await withUiaClient(client => {
+  const root = client.elementFromHandle(hwnd);
+  if (root === null) {
+    return [];
+  }
+
+  const found: string[] = [];
+  const walk = client.walk({
+    root,
+    maxElements: 400,
+    maxMilliseconds: 400,
+    shouldVisit: ({ controlType, isOffscreen }) => !isOffscreen && controlType !== UiaControlType.button
+  });
+  for (const node of walk) {
+    const ranges = node.pattern("text")?.visibleRanges() ?? [];
+    found.push(...ranges.map(range => range.getText(1000)));
+  }
+
+  return found;
+});
+```
+
+| Call | What |
+|---|---|
+| `withUiaClient(use)` | creates `CUIAutomation`, runs `use(client)`, releases everything; an element used after that throws `UiaScopeEndedError` |
+| `client.elementFromHandle(hwnd)`, `client.focusedElement()` | an element, or null when it is gone or cannot be read |
+| `element.properties()` | `name`, `className`, `automationId`, `controlType`, `processId`, `isOffscreen`, `boundingRectangle`, `headingLevel` (0 for none, 1 to 9), `hasTextPattern`, `hasValuePattern` |
+| `client.walk({ root, maxElements, maxMilliseconds, shouldVisit })` | breadth first over the control view, one cached call per parent (`FindAllBuildCache`); `walk.end` is `complete`, `maxElements` or `deadline`; an element that went away is skipped; `node.skipSubtree()` prunes |
+| `element.pattern("text")` | `visibleRanges()`, `documentRange()`, and `range.getText(maxLength)` |
+| `element.pattern("value")` | `value` |
+| `readWindowText({ client, root })` | the headings and text of a window, skipping chrome and off screen elements (`UIA_CHROME_CONTROL_TYPES`); `version` changes when the text does |
+| `createUiaWorker()` | `readText({ target, excludeProcessId, hardMilliseconds, ... })` with the hard deadline; `close()` |
+| `UiaControlType`, `UiaPropertyId`, `UiaPatternName`, `HEADING_LEVEL_NONE`, `HEADING_LEVEL_FIRST` | the header's ids as `as const` sets and constants (the sets also under `winui-svelte/enums`) |
+| `UiaWalkEnd`, `TextBlockKind`, `UiaTarget` | the closed sets of a walk's end, a block's kind and a worker target (`foreground`, `focused`, or `{ hwnd }`) |
+| `UiaElementUnavailableError`, `UiaScopeEndedError`, `UiaTimeout` | the errors: an element went away, a client was used after its scope, a target did not answer in time |
+
+Elements an app cannot read (elevated windows) come back as null, never an
+exception; browsers and Electron build their tree when the first client asks,
+so the first walk of such a window can be slower
+
 ## Windows devices (`winui-svelte/devices`)
 
 Windows' own device APIs (`Windows.Devices.*`, `Windows.System.Power`,