winui-svelte 0.0.6 → 0.0.8

package/API.md

@@ -35,16 +35,20 @@ monorepo needs no build step (the repository is a pnpm workspace, see
 | `winui-svelte/runner` | `src/vite/runner.ts` | `createWindowModuleRunner()`, the window thread's side of the module server |
 | `winui-svelte/compile` | `src/vite/compile.ts` | `compileSvelte()` for bundlers (esbuild) and tests, `WINUI_COMPILE_OPTIONS`, `withElementAnimation()` |
 | `winui-svelte/testing` | `src/vite/loader.ts` | `svelteHooks()`: Node module hooks that run `.svelte` files, with Svelte's runtime read through the package's edits (pure tests) |
-| `winui-svelte/bootstrap` | `src/window/bootstrap.ts` | `initWindowsAppSdk()`; imports nothing of WinRT, safe on the host's main thread |
+| `winui-svelte/bootstrap` | `src/window/bootstrap.ts` | `initWindowsAppSdk()`, `hasPackageIdentity()`, `processDpiAwareness()`, `BootstrapMode`, `DpiAwareness`; 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()`, `startTray()`, `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()`, `claimInstance()`, `isInstanceRunning()`, `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/native-messaging` | `src/app/native-messaging/index.ts` | `registerNativeMessagingHost()`, `unregisterNativeMessagingHost()`, `NativeMessagingBrowser` (opt-in; see Native messaging host) |
+| `winui-svelte/win32` | `src/win32/index.ts` | `bindDll()`, `bind()`, `hasPackageIdentity()` and the memory helpers (opt-in escape hatch; see Win32 seam) |
 | `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/security` | `src/security/index.ts` | `protectData()`, `unprotectData()`, `wipe()`, `ProtectionScope`, `DataProtectionError`: Windows DPAPI, compatible with .NET `ProtectedData` (opt-in; see Security) |
 | `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) |
 
@@ -52,17 +56,20 @@ monorepo needs no build step (the repository is a pnpm workspace, see
 | `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/input` | `src/input/index.ts` | `enableInputEvents()`, `setPointerCapture` / `releasePointerCapture` / `hasPointerCapture`, `activeElement()`, `modifierKeysHeld()`, `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/manifest` | `src/win2d/manifest.ts` | `win2dActivatableClasses`, `win2dClassNames`: the manifest fragment a packaged app needs for Win2D (see Packaged apps) |
 | `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/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
@@ -706,14 +713,75 @@ for tools; `compileSvelte()` throws an `Error` with that message
 // match wins), sets WINAPPSDK_BOOTSTRAP_DLL_PATH, puts the folder it was found
 // in on PATH (WebView2's native libraries are there) and initialises the
 // Windows App SDK. Sets WEBVIEW2_USER_DATA_FOLDER to `webViewUserDataFolder`
-// unless it is already set. Throws WindowsAppRuntimeMissing when the runtime is
-// not installed.
+// unless it is already set; `false` leaves it alone (the variable overrides the
+// folder of a createWebView2Environment). Throws WindowsAppRuntimeMissing when the runtime is
+// not installed. In a process whose package graph holds the Windows App SDK
+// (an MSIX whose manifest declares the PackageDependency) it skips the
+// bootstrapper, which refuses to run there with 0x80070032; the environment
+// and PATH steps still run, and the bootstrapper need not be found.
 function initWindowsAppSdk(options?: {
   major?: number;
   minor?: number;
   folders?: string[];
-  webViewUserDataFolder?: string;
-}): void;
+  webViewUserDataFolder?: string | false;
+  dpiAwareness?: DpiAwareness | undefined;   // default "per-monitor-v2"; undefined leaves the process as it is
+  bootstrap?: BootstrapMode;                 // default "auto"
+}): { runtime: RuntimeSource };               // "package" or "bootstrapper", for a log line
+
+// auto: skip the bootstrapper when the package graph holds a Microsoft.WindowsAppRuntime
+// framework package, call it otherwise; always: call it (an error surfaces as
+// WindowsAppRuntimeMissing with the original in `cause`); never: skip it
+const BootstrapMode = { auto: "auto", always: "always", never: "never" } as const;
+const RuntimeSource = { bootstrapper: "bootstrapper", package: "package" } as const;
+
+// Whether this process has a package identity (MSIX or sparse package); cheap,
+// kernel32 only, no WinRT
+function hasPackageIdentity(): boolean;
+
+// The process's DPI awareness. node.exe is unaware, so every window reads 96
+// DPI (`scaleOf` 1) and screen captures and monitor rectangles are virtualized
+// on a display above 100%. `initWindowsAppSdk` asks for per-monitor v2 first,
+// before WinUI starts: Windows allows it once per process and only before the
+// first window exists, so a library that creates a window before the call
+// keeps an unaware process. A refusal is success when the process already has
+// at least that awareness (a manifest set it); otherwise it throws
+// DpiAwarenessTooLow, naming both values.
+const DpiAwareness = {
+  unaware: "unaware", system: "system", perMonitor: "per-monitor", perMonitorV2: "per-monitor-v2"
+} as const;
+type DpiAwareness = (typeof DpiAwareness)[keyof typeof DpiAwareness];
+function processDpiAwareness(): DpiAwareness;   // from GetThreadDpiAwarenessContext
+
+const { runtime } = initWindowsAppSdk();        // per-monitor v2; "package" when packaged
+initWindowsAppSdk({ bootstrap: BootstrapMode.always });
+initWindowsAppSdk({ dpiAwareness: undefined }); // leave the process alone
+processDpiAwareness();                          // "per-monitor-v2"
+```
+
+### Packaged apps
+
+An MSIX app whose manifest declares
+`<PackageDependency Name="Microsoft.WindowsAppRuntime.2" .../>` runs with the
+runtime already in its package graph, so WinRT and WinUI activate with no
+bootstrapper; `initWindowsAppSdk` sees that and skips it (`runtime: "package"`)
+A child process has the identity only when the packaged parent started it
+A package that has an identity but no such dependency (a sparse package) still
+calls the bootstrapper, which Windows refuses with `0x80070032` in any packaged
+process; declare the dependency
+`test/packaged-bootstrap.test.ts` proves it with a throwaway package
+(`WINUI_SVELTE_PACKAGED_TEST=1 pnpm test:windows test/packaged-bootstrap.test.ts`),
+and `test/support/test-package.ts` is the harness for any test that needs an
+identity: register a loose layout package, run a script under it, remove it
+
+An application manifest is the static route for a single executable: embed it
+as the `RT_MANIFEST` resource (id 1, type 24) with `<dpiAware>true/pm</dpiAware>`
+and `<dpiAwareness>PerMonitorV2,PerMonitor</dpiAwareness>` after the injection
+and before signing, with a PE resource editor (`postject` cannot write it);
+the call is then a no-op that reports success, and stays as the safety net for
+`pnpm dev` under plain `node.exe`; the repository has no single-executable
+build yet, so the embedding step belongs to that work
+
+```ts
 
 // thread (in the worker that owns the UI thread; WinUI's loop never gives its
 // thread back): enters the single-threaded apartment first, so everything
@@ -752,6 +820,7 @@ 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 });
 
@@ -1187,6 +1256,8 @@ Items come in two forms
 keep a row only for each item the control has realized; a `TreeView` also takes
 `children` (the items under an item) and `bind:expandedKeys`, and a `ListView`
 or `GridView` can show its items in groups (`groupBy`, `groupHeader`)
+A hot update of a component an `item` snippet uses shows in the rows already
+realized, with no restart
 A
 control whose items are controls takes them as Svelte's own blocks: `{#each}`
 in the children of `ComboBox`, `FlipView` and `ListBox`, or in the snippet of
@@ -1684,13 +1755,152 @@ const bridge = defineMessaging<AppProtocol>({ transport: createPageTransport() }
 | `executeScript({ control, code })` | runs script in the page and resolves with its JSON value, checked |
 | `addDocumentCreatedScript({ control, code })` | runs script before every page script; resolves with the function that removes it |
 | `openDevTools(control)` | opens the developer tools window |
+| `createWebView2Environment({ browserExecutableFolder, userDataFolder, additionalBrowserArguments, language })` | builds an environment: a profile folder and Chromium switches (an array, joined with spaces) |
+| `startWebView2({ control, environment, profileName, isInPrivateMode })` | starts the control's browser in that environment and resolves with its `CoreWebView2`; a second call on the control resolves with the same core |
+| `keepWebView2Alive({ control, setup, rebuild, maxCrashes, windowMilliseconds, onRecovering, onGaveUp })` | brings a control back after a browser crash (see below); resolves with a guard that has `retry()` and `dispose()` |
 | `getCookies`, `setCookie`, `deleteCookie` | the profile's cookies as plain data (`CookieSameSite`) |
 | `onPermissionRequested({ control, decide })` | answers permission requests with a `PermissionState` (`default`, `allow`, `deny`) for a `PermissionKind` |
 | `onDownloadStarting({ control, pathFor })` | sends a download to a path with no dialog, or cancels it with `null` |
 | `onNavigationStarting({ control, isAllowed })` | cancels the navigations `isAllowed` refuses |
+| `blockRequests({ control, uri, context, statusCode })` | answers every request to a URI pattern (`*` and `?` wildcards) with an empty `204` until the returned function is called |
+| `onWebResourceRequested({ control, filters, respond })` | `respond(request)` returns `null` to let a request through or `{ statusCode, reasonPhrase, headers, body }` to answer it; `filters` are `{ uri, context }` with a `ResourceContext` |
+| `callDevToolsMethod({ control, method, parameters })` | calls a DevTools protocol method, resolves with its result as checked JSON, rejects with the protocol's error |
+| `onDevToolsEvent({ control, event, handler })` | hands the parsed parameters of a protocol event to `handler`; the domain must be enabled first (`Network.enable`) |
+| `dispatchKey`, `dispatchMouseClick`, `typeText`, `keyEventParameters`, `KeyEventType`, `MouseButton` | trusted input through `Input.dispatchKeyEvent` and `Input.dispatchMouseEvent`; `typeText` takes a `TypeMode` (`keys`, or `insertAfterFirst`) |
+
+#### Crash recovery
+
+When Chromium's browser process dies the control is dead: every later call
+throws, and starting it again in place is not something to rely on
+`keepWebView2Alive` follows `CoreProcessFailed` and applies one policy
+
+```ts
+import { keepWebView2Alive } from "winui-svelte/messaging/web-view2";
+
+const guard = keepWebView2Alive({
+  control,
+  maxCrashes: 3,
+  windowMilliseconds: 30_000,
+  async setup(core) {
+    // runs for the first core and after every rebuild
+    await core.addScriptToExecuteOnDocumentCreatedAsync(bridgeScript);
+  },
+  onRecovering: ({ kind }) => status("reconnecting"),
+  onGaveUp: ({ reason }) => status("down"),
+  rebuild: async () => remount()
+});
+guard.dispose();
+```
+
+- `ProcessFailureKind` (`winui-svelte/enums`) is `BROWSER_EXITED`,
+  `RENDER_EXITED`, `UNRESPONSIVE` or `OTHER`, mapped from
+  `CoreWebView2ProcessFailedKind`
+- `BROWSER_EXITED` calls `rebuild`, which resolves with a new control that is
+  already started (`startWebView2`), then runs `setup` with its core; any other
+  kind calls `core.reload()` and keeps the core
+- More than `maxCrashes` failures within `windowMilliseconds` (3 within 30
+  seconds by default) call `onGaveUp` once and stop; `retry()` forgets the
+  failures and rebuilds
+- A failure while a recovery is running is ignored; a `rebuild` or `setup` that
+  throws gives up with the error's text as the reason
+- After a rebuild, redo in `setup` whatever is bound to the old core: scripts
+  from `addDocumentCreatedScript`, `onNavigationStarting`,
+  `onPermissionRequested`, `onWebResourceRequested`, the DevTools subscriptions
+  and a `webView2Transport` with its messaging; cookies and storage live in
+  the profile folder and survive; after a reload only the page's own state is
+  lost
+- In a Svelte app, key the component on a `$state` counter: `rebuild` bumps
+  it and resolves with the control that the new `WebView2` hands to
+  `oncorewebview2initialized`; `examples/web-recovery` shows it, and
+  `test/web-recovery.test.ts` kills its browser process and sees the page come
+  back
+- Several controls on one profile folder share a browser process, so one kill
+  fails all of them; each control has its own guard, and each rebuilds itself
+- Resuming what a page was doing (a live conversation) is the app's job;
+  `onRecovering` is its hook
+
+A profile folder and Chromium switches per control
+
+```ts
+import { createWebView2Environment, startWebView2 } from "winui-svelte/messaging/web-view2";
+
+const environment = await createWebView2Environment({
+  userDataFolder: path.join(process.env.LOCALAPPDATA, "MyApp", "WebView2Home"),
+  additionalBrowserArguments: ["--autoplay-policy=no-user-gesture-required"],
+  language: "en-US"
+});
+// control is the WebView2 (the sender of onloaded), already in a window
+const core = await startWebView2({ control, environment, profileName: "home" });
+```
+
+- The first start of a control wins: call `startWebView2` before anything that
+  starts it with the default environment (`waitForCoreWebView2` and every
+  helper that calls it); a second call resolves with the same core
+- `WEBVIEW2_USER_DATA_FOLDER` overrides the folder of an environment (measured:
+  with it set, two environments with two folders both ran in the variable's
+  folder), so the app starts with `initWindowsAppSdk({ webViewUserDataFolder: false })`
+  and the variable unset
+- One browser process runs per folder; two controls in one folder with different
+  options, or a process that cannot launch the browser, fail with 0x8007139F,
+  and a folder another browser has open with 0x800700AA; the rejection's message
+  names the causes
+- `additionalBrowserArguments` reach the browser process (the test reads its
+  command line); profiles of different folders share no cookies
+- `core.browserProcessId` and `core.environment.userDataFolder` are on
+  `CoreWebView2Like`
+- `examples/web-profiles` and `test/web-profiles.test.ts` run two controls in
+  one window with two folders; it needs an ordinary desktop session
+
+Request filters and the protocol
+
+```ts
+import {
+  blockRequests,
+  callDevToolsMethod,
+  ResourceContext,
+  typeText
+} from "winui-svelte/messaging/web-view2";
+
+const unblock = await blockRequests({
+  control,
+  uri: "https://accounts.google.com/RotateCookies*",
+  context: ResourceContext.ALL
+});
+await callDevToolsMethod({ control, method: "Runtime.evaluate", parameters: { expression: "document.title" } });
+await typeText({ control, text: "hello" });
+unblock();
+```
+
+- A filter added before the first navigation applies to it; one added later
+  does not apply to requests already in flight
+- Every handler hears the requests of every filter of the control, so each
+  checks its own filters; `respond` is a plain function (the answer is given
+  before the event's handler returns), and a body holds the request until it
+  is written to a stream
+- The empty answer uses an empty `InMemoryRandomAccessStream`; a `null` stream
+  for `createWebResourceResponse` was not tried
+- Typing 300 characters with `typeText` takes 5 to 7.5 seconds in a window on
+  this machine (two protocol calls per character, sent in order: sending them
+  all at once reorders the keys); `TypeMode.INSERT_AFTER_FIRST` takes about
+  0.1 second, but whether a page enables its Submit button from inserted text
+  is the page's
+- `coreWebView2` is not set yet inside `oncorewebview2initialized`; the helpers
+  that wait for it need a turn of the event loop first (`setTimeout`)
+
+Porting a C# WebView2 host
+
+| C# | Here |
+|---|---|
+| `CookieManager` | `getCookies`, `setCookie`, `deleteCookie` |
+| `PermissionRequested` | `onPermissionRequested` |
+| `NavigationStarting` | `onNavigationStarting` |
+| `AddWebResourceRequestedFilter` and `WebResourceRequested` | `StatusCode`, `blockRequests`, `onWebResourceRequested` |
+| `CallDevToolsProtocolMethodAsync` | `callDevToolsMethod`, `dispatchKey`, `dispatchMouseClick` |
+| `GetDevToolsProtocolEventReceiver` | `onDevToolsEvent` |
 
 `examples/web-bridge` is an app talking to a hosted page, and
-`test/web-bridge.test.ts` runs it in a real window; it needs an ordinary
+`test/web-bridge.test.ts` runs it in a real window; `examples/web-requests` and
+`test/web-requests.test.ts` do the same for a blocked request and typed input; it needs an ordinary
 desktop session (a sandboxed process cannot launch the browser, 0x8007139F)
 
 ### ListView and GridView
@@ -1883,6 +2093,15 @@ exists on Windows 11 only
 A window on a desktop of its own (a hidden desktop) is never composed by
 Windows, so there is nothing to see through to: `test/transparent-window.test.ts`
 reads the screen of the ordinary desktop for that reason
+`isClickThrough` with `backdrop="transparent"` works on build 26300, measured
+by `test/click-through.test.ts` (examples/click-through, a 3 px ring drawn by
+content): the window stays clear (the hole reads the desktop, the ring its
+color, not black), and a click on the ring and one in the hole reach the window
+below, as Windows hit-tests it (`WindowFromPoint`, the root's owner); the same
+ring without `isClickThrough` answers itself, which is the control
+No region (`clipToRing`) is needed, and the host's own order of the frame and
+the backdrop is the one that was measured
+The test sends no click, so a person still confirms it in Notepad (CONTRIBUTING)
 Not checked: a filter or a drop shadow (`filter: drop-shadow()`) on content
 over a transparent window
 The window's own `cornerRadius` clips with an edge that is not anti-aliased, so
@@ -1970,11 +2189,40 @@ along the top, until `isResizable={false}` takes it away),
 `isShownInSwitchers` and `isToolWindow` (no taskbar button or Alt+Tab entry),
 `isActivatable={false}` (a click never takes focus), `isClickThrough`,
 `isExcludedFromCapture` (black in screenshots and screen sharing),
-`isHidden` (opens hidden, hides and shows later) and `cornerRadius` (clips the
+`isHidden` (opens hidden, hides and shows later), `isParked` (see below) and `cornerRadius` (clips the
 window to a rounded rectangle; the edge is not anti-aliased, so on a
 transparent window round the card's own `corner-radius` instead, which is)
 A prop left out leaves the window as it is, and dropped again it puts the
 window back
+
+A window that must run but never be seen (a host for a page with no UI) is
+`isParked`: shown, so that Chromium keeps its page at full speed, but a tool
+window that is not activatable, opened without taking focus, and placed left of
+the virtual screen, clear of every display
+`placement` and `width`/`height` give only its size; dropping the prop moves it
+back
+It is the per-window form of the `WINUI_SVELTE_BACKGROUND` run, and uses the
+same code
+`isHidden` is not a substitute: a hidden window is a hidden page
+(`document.visibilityState` is `hidden`, timers are throttled)
+`test/parked-window.test.ts` measures it: the page of a parked window reports
+`visible`, a heartbeat of 100 milliseconds keeps its pace and
+`requestAnimationFrame` keeps firing, where the same window with `isHidden`
+reports `hidden`
+Measured over 5 seconds, no Chromium flags set (the default WebView2
+environment):
+
+| Window | `visibilityState` | Heartbeat gap (100 ms timer) | Frames |
+|---|---|---|---|
+| `isParked` | `visible` | under 150 ms on average | above 10 a second |
+| `isHidden` | `hidden` | slower, throttled | not measured |
+
+So the three Chromium flags the C# host sets are not needed for a parked window
+```svelte
+<Window isParked width={900} height={720}>
+  <WebView2 source="about:blank" />
+</Window>
+```
 `createWindow` takes them too
 `handle.setShownInSwitchers(isShown)` does not throw for a window that has no
 taskbar button (WinUI answers 0x80004001 there); `hideToTray` uses it
@@ -2033,6 +2281,46 @@ at the size it has after Windows rescaled it
 The arithmetic is plain functions (`anchoredBounds`, `dockedBounds`,
 `fittedBounds` in `src/window/anchor.ts`) over device pixels
 
+### Covering a display
+
+```ts
+// the whole display the user is on, in physical pixels
+handle.cover({ display: DockDisplay.active })
+// a rectangle of the display, from its top left
+handle.cover({ display: DockDisplay.current, region: { x: 240, y: 120, width: 800, height: 600 } })
+// one display by the id that displays() lists
+handle.cover({ display: displayId })
+```
+
+A covering window needs `isBorderless` and `isResizable={false}`: without the
+second, the 8 device pixel resize frame stays, shrinks the client area and
+paints a strip along the top; `cover` does not set either, because a prop left
+out leaves the window as it is
+`dock` is a corner of the **work area** at the window's own size; `cover` is
+the **whole display** (or a part of it) at the display's size;
+`handle.geometry` is in CSS pixels at the window's scale and can do neither
+exactly
+`display` is a `DockDisplay` or a display id (a `bigint`); the active display by
+default
+`region` is in the target display's own physical pixels, relative to its top
+left, and is not clipped to it, so a frame drawn 4 pixels outside a region at
+the display's edge stays where it was asked for; a region measured on another
+display has to be mapped by the caller
+It returns the bounds it applied (`WindowBounds`), so a frame or a canvas can
+follow them
+A window sent to a display with another scale first goes to that display's
+origin, so Windows rescales it there, and is then placed once at the bounds in
+that display's pixels; a rescale that changed the size anyway is placed again
+(at most twice)
+`coverWindow({ appWindow, display, region })` (`winui-svelte/window`) does the
+same for a bare `AppWindow`, and `coveredBounds` in `src/window/anchor.ts` is
+the plain arithmetic
+`outerBounds` and `appWindow` are physical pixels only in a PerMonitorV2
+process
+Not verified: whether a topmost window that equals a monitor's bounds changes
+the taskbar for that monitor, and whether a `backdrop="transparent"` cover is
+see-through at its edge pixels; try both before shipping an overlay on them
+
 `handle.geometry` is the window's own `window.outerWidth`, `outerHeight`,
 `screenX`, `screenY`, `devicePixelRatio`, `resizeTo(width, height)`,
 `resizeBy`, `moveTo(x, y)` and `moveBy`, in CSS pixels (WinUI's
@@ -2560,9 +2848,22 @@ An opt-in subpath: an app that does not import it does not bundle it
   The running copy's `onRedirect` receives `activation`
 - `launchApp({ command, arguments, workingDirectory })` starts a program
   that outlives the caller: detached, no console window, no shared handles
+- `claimInstance({ key, source, activation, runOnUiThread, onRedirect })` is `ensureSingleInstance` over any source of the link
+  Pass `createPipeSource()` to claim the pipe early on a plain main thread,
+  before any WinUI loads, so a second copy exits in about 50 ms; it needs no
+  dispatcher queue, and `runOnUiThread` relays `onRedirect` to the thread that
+  owns the windows (`pipeNameFor` and `currentUserSid` are the pipe's name
+  and its user)
 - `activateOrLaunch({ key, activation, launch })` is the two together: it
   activates the running copy, or else starts the app with `launch`, and
   resolves with true for the first and false for the second
+- `activateInstance` and `launchApp` first call `AllowSetForegroundWindow` for
+  any process, as does the standalone tray after a menu pick and before a
+  click's handler: Windows' foreground lock refuses the window of another
+  process, and only the process that received the user's input can lift it
+  `handle.bringToFront()` also joins the foreground thread's input (the same
+  call as `bringWindowToFront`), so a window asked from another process comes
+  to the front instead of flashing on the taskbar
 - `relaunch({ arguments })` starts the same Node with the same flags, entry
   script (`process.argv[1]`) and then `arguments`, detached, and calls
   `exitApplication`, so the new copy outlives this one
@@ -2571,9 +2872,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
@@ -2595,10 +2900,12 @@ import {
   ActivationKind,
   installProtocolHandlers,
   launchAtLogin,
+  packagedActivation,
   registerFileTypes,
   startActivation,
 } from "winui-svelte/app/activation";
 
+const packaged = packagedActivation(); // { kind: "protocol", uri } or { kind: "startup" }
 installProtocolHandlers();
 navigator.registerProtocolHandler("note", "https://notes.example/open?uri=%s");
 registerFileTypes({ id: "com.example.notes", extensions: [".note"] });
@@ -2626,6 +2933,7 @@ if (!single.isPrimary) {
 | `unregisterFileTypes({ id, extensions })` | deletes both and the empty keys left | returns the extensions removed |
 | `launchAtLogin({ id, isEnabled, arguments })` | `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` value `id` | listed in Settings, Apps, Startup; the start arrives as `startup` |
 | `getLaunchAtLogin({ id })` | reads that value | `{ isEnabled, commandLine }`; the user's switch in Settings is not read |
+| `packagedActivation()` | `AppInstance.getActivatedEventArgs()` | how a packaged process was started; `undefined` outside a package |
 | `startActivation({ key, onActivation })` | `ensureSingleInstance` and the command line | one `ActivationEvent` per start or redirect |
 
 - `ActivationEvent` is a union on `kind` (`ActivationKind`, also from
@@ -2665,18 +2973,116 @@ if (!single.isPrimary) {
   characters at most) and handed to your code, never run
   Windows can pass a quote in a link through `"%1"` unescaped, so treat the
   whole of `uri` as untrusted
+- Packaged apps: a package declares its scheme in the manifest, so
+  `installProtocolHandlers` is not needed; `startActivation` reads the start
+  from two places and merges them, the command line first
+  1. Route A, the command line: give the protocol `Parameters`, and Windows
+     passes the address as an argument, for a cold start
+
+     ```xml
+     <Extensions>
+       <uap3:Extension Category="windows.protocol" Executable="my-app.exe"
+           EntryPoint="Windows.FullTrustApplication">
+         <uap3:Protocol Name="my-scheme" Parameters="&quot;%1&quot;" />
+       </uap3:Extension>
+     </Extensions>
+     ```
+
+  2. Route B, the Windows App SDK: `packagedActivation()` reads
+     `AppInstance.getCurrent().getActivatedEventArgs()`; a `Protocol`
+     activation gives its address and a `StartupTask` activation is a
+     `startup` event, which Route A cannot say (a startup task takes no
+     `Parameters`)
+
+     ```xml
+     <desktop:Extension Category="windows.startupTask" Executable="my-app.exe"
+         EntryPoint="Windows.FullTrustApplication">
+       <desktop:StartupTask TaskId="Startup" Enabled="false" DisplayName="My app" />
+     </desktop:Extension>
+     ```
+
+  An address the command line holds wins over the activation's; a later
+  copy's address arrives through the single instance link as a redirect, as
+  everywhere, so never call `redirectActivationToAsync`
+  `packagedActivation()` answers `undefined` outside a package, for a plain
+  launch and for any failure; it never throws
+  Call `startActivation` after `initWindowsAppSdk` (`initWindowsAppSdk`)
 - Needs packaging for: the share target and a default-app claim (a package
   manifest declares them); unpackaged, the app is offered in Open with and the
   user picks the default
 - `installProtocolHandlers()` returns the function that removes the two
   navigator methods; the registrations stay until you unregister them
   Each registration function takes `registry` (a fake in tests) and `command`
+- `test/packaged-activation.test.ts` (opt in with `WINUI_SVELTE_PACKAGED_TEST=1`)
+  registers a throwaway package with both routes and starts it with a link
 - `src/app/activation/native.test.ts` registers a protocol, a file type and a
   startup entry under HKCU with a unique name, reads them with `reg query`,
   removes them and checks nothing is left, even when it fails;
   `test/activation.test.ts` starts real second copies with a link, a file and
   nothing, and checks the first hears each as one event
 
+### Native messaging host (`winui-svelte/app/native-messaging`)
+
+Telling the browsers where a native messaging host lives, for the current user
+
+```ts
+import { registerNativeMessagingHost } from "winui-svelte/app/native-messaging";
+import { isInstanceRunning } from "winui-svelte/app";
+
+registerNativeMessagingHost({
+  name: "com.example.notes",
+  manifestPath: "C:\Users\me\AppData\Local\Notes\host.json",
+});
+
+const isAppUp = isInstanceRunning({ key: "com.example.notes" });
+```
+
+- `registerNativeMessagingHost({ name, manifestPath, browsers, registry })`
+  writes the manifest's path as the default value of
+  `HKCU\Software\<browser>\NativeMessagingHosts\<name>` for Chrome, Edge,
+  Brave and Chromium (`NativeMessagingBrowser`; pass `browsers` for fewer)
+  It writes the registry only: the JSON manifest is the caller's file
+  Calling it again rewrites the same values; a name other than lowercase
+  letters, digits, `_` and `.` between them, or a relative path, is a
+  `TypeError`
+- `unregisterNativeMessagingHost({ name, browsers, registry })` deletes the
+  host's own keys and each parent left empty; a key that holds anything else
+  stays
+- Under a package identity the write is virtualized unless the manifest
+  declares `desktop6:RegistryWriteVirtualization` as disabled and the
+  `unvirtualizedResources` capability; browsers read the real registry
+- `isInstanceRunning({ key })` is true while a copy serves `key`
+  (`ensureSingleInstance` or `claimInstance`); it asks the pipe's existence,
+  sends nothing and never starts or claims anything, so a host can ask
+  before it starts the app
+
+### Win32 seam (`winui-svelte/win32`)
+
+An escape hatch for a Win32 function that WinRT has no equivalent for, over
+the binder the package uses itself
+
+```ts
+import { bindDll, hasPackageIdentity } from "winui-svelte/win32";
+
+const user32 = bindDll({
+  dll: "user32.dll",
+  functions: { foreground: ["GetForegroundWindow", [], "pointer"] },
+});
+const hwnd = user32.foreground();
+```
+
+- `bindDll({ dll, functions })` takes one `[entryPoint, parameters,
+  returnType]` row per name and calls with plain values (numbers, bigints,
+  strings as wide text, memory, null) and gives back a number or an address
+- `bind(...)` is the lower level one, over `DynWin32` values
+  `pointerOf`, `wideMemory`, `numberOf`, `addressOf`, `withMemory` and
+  `WIDE_CHAR_BYTES` are its helpers; the caller owns the memory it allocates
+- `hasPackageIdentity()` tells a packaged process from plain Node
+- Types are strings and `@microsoft/dynwinrt` is a preview, so this entry may
+  change with it; the registry has its own typed entry
+  (`createWindowsRegistry` in `winui-svelte/app/activation`, string values of
+  the current user only)
+
 ### Jump list tasks (`winui-svelte/app/jump-list`)
 
 Entries in the Tasks section of the taskbar button's right-click menu
@@ -2926,6 +3332,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
@@ -3127,8 +3592,13 @@ const lines = resolveMenu({
   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
+- `icon` is a path, a glyph, `IconPixels`, `{ forLightMenu, forDarkMenu }` (one
+  picture for each menu theme) or `{ tinted }` (a single-color glyph that the
+  menu paints in its text color, so one picture serves both themes); each
+  renderer draws what it can (the popup menu of `winui-svelte/tray/standalone`
+  draws files and pixels, a flyout draws paths and glyphs, and takes the light
+  member of a pair)
+  `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)
@@ -3324,13 +3794,19 @@ createStandaloneTray({
   `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
+  Four 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
+  `balloons` adds `notify`, `bounds` adds `bounds()`, `themedIcon` lets
   `icon` be `{ forLightTaskbar, forDarkTaskbar }`, swapped as the taskbar theme
-  changes
+  changes, and `menuIcons` draws the icons of the menu's lines (below)
   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
@@ -3369,12 +3845,29 @@ tray.notify({ title: "Ready" });
   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
+  A submenu's own `onselect` and `autoExpand` do nothing here: Windows opens a
+  submenu row without reporting a pick
+  Without `menuIcons` in `extras` no line shows an icon, and the roughly 6 KB
+  of the decoder and the bitmap code stay out of the bundle
+  With it, every `icon` is drawn as a bitmap beside the label, on commands,
+  checks, radios and submenu rows at any depth: a path to a png, ico, bmp, jpeg, gif
+  or tiff (decoded by GDI+, kept by path and modification time, so a menu that
+  opens again does not decode again), `IconPixels`, a `{ forLightMenu,
+  forDarkMenu }` pair, or `{ tinted }` for a monochrome glyph (only its alpha is
+  used, and it takes the menu's text color)
+  The theme is read each time the menu opens, by the rule `colorScheme` sets
+  (the system's app mode for `"light dark"`), so a pair and a tinted glyph
+  follow a theme change; the bitmap is a 32-bit premultiplied DIB section, the
+  size of the menu's check mark at the screen's scale (at least the small icon
+  size), and is freed with the menu
+  A disabled line gets a grey, fainter icon (Windows does not dim a bitmap),
+  and a ticked line or radio gets a frame around its icon, because Windows
+  draws the icon where the tick would be
+  A path that cannot be read leaves the line without an icon; the rest of the
+  menu opens as usual
   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
@@ -3385,6 +3878,76 @@ tray.notify({ title: "Ready" });
   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
@@ -3425,6 +3988,14 @@ export default defineTray({
 - `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
@@ -3773,6 +4344,46 @@ const lines = menus.menu(ContextMenuSurface.TRAY);
   `ContextMenuSurface`, `ContextType`, `ChromeEvent`, and the types
   `CreateProperties`, `OnClickData` and `UpdateProperties`
 
+## Security (`winui-svelte/security`)
+
+Windows DPAPI for secrets an app keeps on disk, with nothing to install: no
+native addon, no WinRT, only the Win32 calls through the package's own binder
+Opt-in: nothing is bundled until an app imports it (about 3 KB), and importing
+does no work
+
+The blob is the one .NET's `ProtectedData.Protect` makes, so a TypeScript app
+reads the files a .NET app wrote with `CurrentUser` scope, and the other way
+round; `ProtectionScope` is `DataProtectionScope`'s two values
+
+```ts
+import { ProtectionScope, protectData, unprotectData, wipe } from "winui-svelte/security";
+
+const sealed = protectData({
+  data: new TextEncoder().encode(apiKey),
+  scope: ProtectionScope.CURRENT_USER
+});
+await writeFile("settings.bin", sealed);
+
+const plain = unprotectData({ data: await readFile("settings.bin") });
+useKey(new TextDecoder().decode(plain));
+wipe(plain);
+```
+
+- `protectData({ data, entropy?, scope?, description? })` returns the sealed
+  bytes; `entropy` is mixed into the key and needed again to unseal
+- `unprotectData({ data, entropy?, scope? })` returns the plain bytes
+- `wipe(buffer)` zeroes a buffer; the native buffers the helper used are zeroed
+  before release, the copies you hold are yours to wipe, and a string cannot be
+  wiped, so keep secrets as bytes
+- `DataProtectionError` carries the Win32 `code` (87 for bytes that are no
+  blob, 13 for a corrupted blob or the wrong entropy); the message never holds
+  the data
+- `MAX_DATA_BYTES` (64 MiB) is the limit of one call; more throws `RangeError`
+- A UI prompt can never appear (`CRYPTPROTECT_UI_FORBIDDEN`)
+- DPAPI offers no recovery: keys follow the user's logon secret, so an
+  administrator's password reset can make old blobs unreadable; a packaged app
+  keeps the same user keys as an unpackaged one
+
 ## Downloads (`winui-svelte/downloads`)
 
 Downloads on the two APIs an app already knows: the web's `fetch` with the File
@@ -4447,8 +5058,12 @@ pixels), `offsetX`/`offsetY` (the control), `altKey`, `ctrlKey`, `shiftKey`,
 `DataTransfer` has `types`, `files`, `items` (`DataTransferItemList`: `length`,
 `at`, `add`, iteration; items have `kind`, `type`, `getAsString`, `getAsFile`),
 `getData(type)`, `setData(type, value)`, `clearData(type?)`, `effectAllowed`
-(`EffectAllowed`), `dropEffect` (`DropEffect`), `setDragImage` (accepted, WinUI
-draws its own preview) and `bitmap` (a picture to drag)
+(`EffectAllowedName`), `dropEffect` (`DropEffectName`), `setDragImage` (accepted,
+WinUI draws its own preview) and `bitmap` (a picture to drag)
+`DropEffect` and `EffectAllowed` hold the names, so an editor suggests
+`DropEffect.link`; `DropEffectName` and `EffectAllowedName` are those names or
+any other string, and an unknown string counts as `none` for a drop effect and
+as `uninitialized` (everything allowed) for `effectAllowed`
 The standard formats are `text/plain` (Text), `text/html` (the fragment of the
 HTML format), `text/uri-list` (Uri), `Files` (StorageItems) and, for a picture,
 a `NativeFile` in `files`; any other format id is a custom text format, listed
@@ -4485,6 +5100,36 @@ window's content to take drops anywhere on the window
 `onDragEnter`, `onDragOver`, `onDragLeave` and `onDrop` take the same
 `DragEvent` as the web names
 
+Which part of the window takes a drag (accepting selectively):
+
+- only a zone takes a drag; a point outside every zone shows the forbidden sign,
+  so a section of the window is the only place that accepts when it alone has
+  `dropzone`
+- the zone under the cursor answers; with nested zones the innermost one
+  decides, and a zone that refuses (its `accept` takes nothing the drag
+  carries) refuses for its whole area even when an outer zone would accept
+- a zone on the root element of the window is the window-wide default; put a
+  zone with a narrower `accept` (or one that refuses) on a section to
+  override it there
+- `accept` is judged per zone, so one window can have a folder-only zone and a
+  text-only zone side by side
+- a drag that started inside the window (a list reordering its own items)
+  carries no files, so a zone with `accept: ["directory", ".zip"]` leaves it to
+  the control
+
+A drag from another app (Explorer, a browser) reaches a WinUI 3 window as an OLE
+drag, and WinUI 3 registers no OLE drop target on its window: without one,
+Windows shows the forbidden sign over the whole window and no `dragenter` ever
+fires
+The first zone of a window registers one (`RegisterDragDrop` on the top-level
+window, `src/data-transfer/ole-drop-target.ts`), and it is revoked with the
+last zone or when the window is destroyed; each call is routed to the zone under
+the cursor by a hit test of the visual tree (`src/data-transfer/window-drop.ts`)
+The data object is read through the classic formats (files and folders as
+`CF_HDROP`, text, a link, HTML); a dragged picture from another app is not read
+yet
+`simulateDrop` stays the way to test a zone without any OLE call
+
 `draggable(options)`: `text`, `html`, `uri`, `files`, `bitmap`, `effectAllowed`,
 and `onDragStart` / `onDrag` / `onDragEnd`
 Drag out to Explorer works with `files` (paths become `StorageFile` and
@@ -4556,6 +5201,170 @@ 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
@@ -4666,6 +5475,10 @@ Everything runs on the UI thread
 </border>
 ```
 
+`modifierKeysHeld()` reads which of Shift, Control and Alt are held right now, as
+`{ shiftKey, ctrlKey, altKey }`, for an action that carries no key state of its
+own (a form submitted with the keyboard, a file picker's result)
+
 `enableInputEvents()` adds the eleven names to the renderer's event-alias table
 (`src/renderer/host/event-adapters.ts`, the one `enableDragEvents()` fills), so a
 raw element takes them
@@ -6210,6 +7023,54 @@ The effect graph is checked on pixels without a window
 (`src/win2d/effect-graph.test.ts`), and the effects in a real window through
 `PrintWindow` (`test/effects.test.ts`, with `examples/effects`)
 
+### Packaged apps
+
+A process with a package identity (an MSIX, or a registered loose layout) finds
+a class through its package's registration catalogue, which lists the classes
+of its framework packages and the `ActivatableClass` entries of its own
+manifest; the `PATH` that `initWindowsAppSdk` sets is not consulted
+Win2D ships no framework package, so every Win2D class fails there with
+`0x80040154` (class not registered) until the manifest names it, and CSS
+`filter: blur()` and every Win2D effect do nothing
+The same app unpackaged (`pnpm dev`) is fine
+
+`win2dActivatableClasses` writes the entries, one `ActivatableClass` of one
+`InProcessServer` per Win2D class the bindings hold; put the result in the
+package's own `<Extensions>` (a child of `<Package>`, after `<Capabilities>`,
+not the application's), with `Microsoft.Graphics.Canvas.dll` in the package at
+`libraryPath`, which `buildApp` writes to `bin/<architecture>`
+
+```ts
+import { win2dActivatableClasses } from "winui-svelte/win2d/manifest";
+
+const fragment = win2dActivatableClasses({
+  libraryPath: "bin/x64/Microsoft.Graphics.Canvas.dll"
+});
+```
+
+```xml
+<Extensions>
+  <Extension Category="windows.activatableClass.inProcessServer">
+    <InProcessServer>
+      <Path>bind\Microsoft.Graphics.Canvas.dll</Path>
+      <ActivatableClass ActivatableClassId="Microsoft.Graphics.Canvas.Effects.GaussianBlurEffect" ThreadingModel="both" />
+    </InProcessServer>
+  </Extension>
+</Extensions>
+```
+
+- `classes` limits the list (an app that only blurs needs a few); by default it
+  is every class the bindings activate by name (`win2dClassNames()`, which
+  reads them from the bindings; `bindings` names another folder)
+- `libraryPath` is per architecture: an x64 and an arm64 package each have
+  their own manifest, and the path is relative to the package root
+- Without the entries a packaged app writes one line to stderr that names this
+  fragment, not one per class
+- `test/win2d-packaged.test.ts` proves it in a real registered package
+  (`WINUI_SVELTE_PACKAGED_TEST=1`, `examples/win2d-packaged`): without the
+  entries the canvas never draws and `0x80040154` is reported; with them it
+  redraws and stderr is empty
+
 ### Canvas 2D (`winui-svelte/win2d/context-2d`)
 
 Opt-in, and a separate subpath: an app that imports only `winui-svelte/win2d`
@@ -6331,6 +7192,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`,