winui-svelte 0.0.7 → 0.0.8

package/API.md

@@ -35,17 +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/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` | `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) |
 
@@ -53,10 +56,11 @@ 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) |
@@ -709,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
@@ -1191,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
@@ -1688,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
@@ -1887,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
@@ -1974,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
@@ -2037,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
@@ -2564,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
@@ -2603,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"] });
@@ -2634,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
@@ -2673,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
@@ -3194,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)
@@ -3399,11 +3802,11 @@ createStandaloneTray({
   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
@@ -3442,9 +3845,26 @@ 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
   `colorScheme` makes it follow the system theme through an undocumented
   uxtheme call; a menu that must be drawn in WinUI belongs in
@@ -3924,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
@@ -4598,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
@@ -4636,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
@@ -4981,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
@@ -6525,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`