winui-svelte 0.0.4 → 0.0.5

package/API.md

@@ -12,16 +12,23 @@ monorepo needs no build step (the repository is a pnpm workspace, see
 
 | Specifier | File | What |
 |---|---|---|
-| `winui-svelte` | `src/index.ts` | `control`, `withControl`, `elementRef`, `elementSize`, `elementTheme`, `focusElement`, `mountControl`, `registerControls`, `setClassHandler`, `dispatch` / `flush` / `onFlush`, the value helpers |
+| `winui-svelte` | `src/index.ts` | `control`, `withControl`, `elementRef`, `elementSize`, `elementTheme`, `focusElement`, `glideHeight`, `mountControl`, `registerControls`, `setClassHandler`, `dispatch` / `flush` / `onFlush`, the value helpers |
 | `winui-svelte/components` | `src/components/generated/index.ts` | every WinUI 3 control as a component (`StackPanel`, `ToggleSwitch`, ...) and its props type (`ToggleSwitchComponentProps`); `xamlOf`, `goToState`, `installXaml`, `resourceDictionaryOf`; importing it registers the generated bindings with the renderer |
 | `winui-svelte/state` | `src/state/index.ts` | `createHostChannel()` (its `messaging` is the typed link), `hostState()`, `StateProtocol`, the transports (stdio, MessagePort, in-memory), `diff` / `applyOps` (see `src/state/README.md`) |
 | `winui-svelte/host` | `src/renderer/host/host.ts` | `renderer`, the renderer WinUI controls are built through (`mountControl` makes it the active one), and the mount-target plumbing below; not for app code |
+| `winui-svelte/scroll-timeline` | `src/web-apis/scroll-timeline.ts` | `installScrollTimeline()`: `ScrollTimeline`, `ViewTimeline` and `element.animate(keyframes, { timeline })` over Composition (the CSS side is `winui-svelte/css/scroll-timeline`, which a sheet that uses `animation-timeline` imports) |
+| `winui-svelte/view-transitions` | `src/web-apis/view-transitions.ts` | `installViewTransitions()`: `document.startViewTransition` and `ViewTransition` over WinUI's connected animations (the CSS side is `winui-svelte/css/view-transition`, which a sheet or style attribute that sets `view-transition-name` imports) |
 | `winui-svelte/element-animation` | `src/renderer/host/element-animation.ts` | `enableElementAnimation()`: what Svelte's `transition:`, `in:`, `out:`, `animate:` and `svelte/motion` ask of an element, on WinUI controls (the Vite plugin calls it from a component that uses them; otherwise not bundled) |
 | `winui-svelte/attached-owners` | `src/components/attached-owners.ts` | `preloadAttachedOwners(names)`: loads the modules attached properties (`canvasLeft`, `gridRow`) are written through (the Vite plugin calls it from a component whose markup or script names one, so the property is set with the control; a prop named nowhere, built from a computed key, needs `await preloadAttachedOwners(["Canvas"])` first, or its control throws) |
+| `winui-svelte/settings` | `src/settings/index.ts` | `SettingsCard`, `SettingsExpander`: Fluent settings cards after the Community Toolkit's (opt-in) |
+| `winui-svelte/implicit-layout-animation` | `src/renderer/host/implicit-layout-animation.ts` | `implicitLayoutAnimation({ duration, easing })`, `LayoutEasing`: children slide to their new places when the layout moves them (opt-in) |
 | `winui-svelte/connected-animation` | `src/renderer/host/connected-animation.ts` | `connectElement({ key, element })`, `startConnected({ key, element })`: WinUI's connected animation between two pages (opt-in) |
+| `winui-svelte/composition` | `src/composition/index.ts` | `animateOnCompositor`, `compositorAnimation`, `visualReference`, `createPropertySet`, the typed expression builder and `scalarSpring` / `vector2Spring` / `vector3Spring`: expression and spring animations on the compositor (opt-in, see "Composition animations") |
 | `winui-svelte/keyed-list` | `src/renderer/list/keyed-list.ts` | `syncKeyed()`: sync a native collection to wanted keys, touching only what changed |
 | `winui-svelte/state` | `src/state/index.ts` | `createHostChannel()`, `hostState()`, the transports (see `src/state/README.md`) |
 | `winui-svelte/messaging` | `src/messaging/index.ts` | `defineMessaging(transport)`: typed `sendMessage` / `onMessage` over a ProtocolMap, as @webext-core/messaging; the state channel is built on it |
+| `winui-svelte/messaging/web-view2` | `src/messaging/web-view2/index.ts` | `webView2Transport({ control })` and the typed `CoreWebView2` helpers (opt-in, see "WebView2 bridge") |
+| `winui-svelte/messaging/page` | `src/messaging/page.ts` | `createPageTransport()`: the web page's end of the link, no WinUI import, safe for a browser bundle |
 | `winui-svelte/vite` | `src/vite/index.ts` | `winuiSvelte()` Vite plugin, `startModuleServer()`, `buildApp()` (the production bundle), compile-error formatting |
 | `winui-svelte/dev` | `src/dev/index.ts` | `startDev()`, the dev loop in one call: Windows App SDK, dev server and the window's thread |
 | `winui-svelte/runner` | `src/vite/runner.ts` | `createWindowModuleRunner()`, the window thread's side of the module server |
@@ -30,14 +37,20 @@ monorepo needs no build step (the repository is a pnpm workspace, see
 | `winui-svelte/bootstrap` | `src/window/bootstrap.ts` | `initWindowsAppSdk()`; imports nothing of WinRT, safe on the host's main thread |
 | `winui-svelte/thread` | `src/window/thread.ts` | `runOnUiThread()`; imports only dynwinrt, so the apartment comes first |
 | `winui-svelte/window` | `src/window/index.ts` | `runWindow()`, `exitApplication()`, `createWindow()`, `startTimer()`, `systemSettings()`, the picker options (see App services) |
-| `winui-svelte/app` | `src/app/index.ts` | `ensureSingleInstance()`, `notify()` (opt-in; see App lifecycle) |
+| `winui-svelte/app` | `src/app/index.ts` | `ensureSingleInstance()`, `notify()`, `activateInstance()`, `activateOrLaunch()`, `launchApp()`, `relaunch()`, `restartAfterCrash()` (opt-in; see App lifecycle) |
+| `winui-svelte/app/activation` | `src/app/activation/index.ts` | `installProtocolHandlers()`, `registerFileTypes()`, `launchAtLogin()`, `startActivation()`, `ActivationKind` (opt-in; see Activation) |
 | `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/input` | `src/input/index.ts` | `enableInputEvents()`, `setPointerCapture` / `releasePointerCapture` / `hasPointerCapture`, `activeElement()`, `moveFocus()`, `trapFocus()`, `PointerType`, `PointerEvent` / `WheelEvent` / `KeyboardEvent` / `FocusEvent` (opt-in; see Input events and focus) |
 | `winui-svelte/media` | `src/media/index.ts` | `bitmapImageOf()`, `svgImageSourceOf()`, `decodeDataUri()`, `createMediaPlayer()`, `mediaSourceOfBytes()`, `observePlayback()`, `PlaybackState` (opt-in; see Media) |
 | `winui-svelte/win2d` | `src/win2d/index.ts` | `Canvas`, the Win2D controls, the drawing helpers and Win2D classes, `applyEffect` (opt-in; see Win2D) |
 | `winui-svelte/enums` | `src/enums.ts` | every closed set a prop or option takes: WinUI's enums, `ThemeBrush`, `ColorKeyword`, `Backdrop`, `WindowTheme`, `TrayBalloonIcon` and the rest (see Closed sets) |
 | `winui-svelte/win2d/context-2d` | `src/win2d/context-2d/index.ts` | `Canvas2D`, `createCanvas2D`, `CanvasElement`, `Context2D`, `Path2D` and the rest of the HTML Canvas 2D API over Win2D (opt-in; see Canvas 2D) |
 | `winui-svelte/tray` | `src/tray/index.ts` | `TrayIcon` (with its `menu`), `createTrayIcon()`, `placeMenuWindow()`, `hideToTray()`, `restoreFromTray()`, `toggleInTray()`, `removeAllTrayIcons()`, `TrayGesture` (opt-in; see System tray) |
+| `winui-svelte/tray/standalone` | `src/tray/standalone/index.ts` | `createStandaloneTray()`, `NativeMenuEntryKind`, and the `winui-svelte/app` calls that start or signal the app: a tray with no window, no WinUI and no components (opt-in; see Tray with no window) |
+| `winui-svelte/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/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
@@ -197,6 +210,57 @@ handed over as it is and read once, when the element is made)
 A property that
 changes is set through `{@attach control(...)}`, as components do
 
+## Wrapping chips
+
+CSS `flex-wrap: wrap` has no WinUI panel to become: the element's tag decides
+the panel, the build does not swap it, and `flex-wrap` stays a build error whose
+message names the two ways below (WinUI 3 has no `WrapPanel`; the Community
+Toolkit's is a separate package)
+Measured in a 300 wide window (`test/chip-tray.test.ts`, the
+`examples/chip-tray` example)
+
+| Way | Wraps | Chip widths | Use it for |
+|---|---|---|---|
+| `RichTextBlock`, a `Paragraph`, each chip in an `InlineUIContainer` | yes, like words in a sentence | each chip keeps its own | link chips, tags, any tray whose items differ in width |
+| `VariableSizedWrapGrid` | yes, at its width or `maximumRowsOrColumns` | one cell for all (the first chip sets it, or `itemWidth` and `itemHeight`) | equal tiles |
+| `ItemsRepeater` with `UniformGridLayout`, `GridView` | yes | one cell for all | the same, with virtualization and selection |
+
+The first row is the answer to `flex-wrap`:
+
+```svelte
+<script lang="ts">
+  import { Border, HyperlinkButton, InlineUIContainer, Paragraph, RichTextBlock } from "winui-svelte/components";
+</script>
+
+<RichTextBlock>
+  <Paragraph>
+    {#each links as link (link.href)}
+      <InlineUIContainer>
+        <Border class="chip">
+          <HyperlinkButton navigateUri={link.href}>{link.label}</HyperlinkButton>
+        </Border>
+      </InlineUIContainer>
+    {/each}
+  </Paragraph>
+</RichTextBlock>
+
+<style>
+  .chip {
+    margin: 0 6px 6px 0;
+  }
+</style>
+```
+
+- The gap between chips is each chip's margin: a `RichTextBlock` has no `gap`
+- Chips sit on the text baseline; `RichTextBlock` has `textAlignment`, which
+  centres or right-aligns the lines
+- The tray is text: a `RichTextBlock` is read-only and takes `isTextSelectionEnabled`
+- Not covered: a CSS rule cannot turn `display: flex; flex-wrap: wrap` into this
+  (a flex container is a `<stack-panel>` or `<grid>` and the build never changes
+  a tag), and `ItemsRepeater` has no layout that flows items of different widths
+  (`UniformGridLayout` is uniform, `LinedFlowLayout` needs one line height and
+  aspect ratios from its items)
+
 ## Transitions (`winui-svelte/element-animation`, `winui-svelte/element-effects`)
 
 Svelte's `transition:`, `in:`, `out:` and `animate:` run unchanged: Svelte's
@@ -294,6 +358,131 @@ What it does:
 - `getComputedStyle` is defined as a global for WinUI's elements; any other
   argument goes to the one that was there, if any
 
+### Gliding a height (`glideHeight`)
+
+WinUI cannot animate `Height="Auto"`, so a card whose content grows or shrinks
+jumps; the web's answer is a `ResizeObserver` plus `element.animate({ height })`,
+and `glideHeight` is that pair as one attachment:
+
+```svelte
+<script lang="ts">
+  import { glideHeight } from "winui-svelte";
+  import { enableElementAnimation } from "winui-svelte/element-animation";
+
+  enableElementAnimation();
+</script>
+
+<border class="card" {@attach glideHeight({ duration: 300, easing: "ease-out" })}>
+  <text-block textWrapping="Wrap">{text}</text-block>
+</border>
+```
+
+- It listens to the element's `SizeChanged`; on a change it runs
+  `element.animate([{ height: from }, { height: to }])`, which sets `Height`
+  explicitly for the glide and gives `Auto` back when it ends (`element.animate`
+  animates `height` and `width` like it does `Opacity` and `Translation`)
+- Needs `enableElementAnimation()` once (a `transition:` directive in the
+  app turns it on too); without it `glideHeight` throws and says so
+- Can: grow and shrink, any easing and duration, a change made during a glide
+  (picked up when it ends), a hot update or removal (the glide is cancelled);
+  reduced motion makes it instant
+- Cannot: glide the first layout, an element with a fixed `height` (it never
+  changes by itself), or the content inside; the layout is already at the new
+  height when the glide starts, so the frame before the first step can show it,
+  and content that would overflow a shrinking card is clipped only if the card
+  clips it (`clip-to-bounds`, a `ScrollViewer`)
+- Measured in a window (`test/card-glide.test.ts`, the `examples/card-glide`
+  example): 250 ms into a 600 ms glide the height lies between the two sizes,
+  both growing and shrinking, and the card ends on its content's height with no
+  fixed `Height` left
+
+### Sliding siblings (`implicitLayoutAnimation`)
+
+When an expander opens, the controls below it jump; on the web a FLIP
+animation slides them, and in WinUI the Composition layer does it with an
+implicit animation on each child's `Offset`
+
+```svelte
+<script lang="ts">
+  import { implicitLayoutAnimation, LayoutEasing } from "winui-svelte/implicit-layout-animation";
+</script>
+
+<stack-panel {@attach implicitLayoutAnimation({ duration: 260, easing: LayoutEasing.EASE_OUT })}>
+  <expander header="Advanced">...</expander>
+  <button>Save</button>
+</stack-panel>
+```
+
+- It is an attachment for a panel; every child that the panel has laid out gets
+  a `Vector3KeyFrameAnimation` on `Offset` that ends at `this.FinalValue`, so
+  the composition layer starts it by itself whenever layout changes the offset
+  (no per-frame work in JavaScript, no `enableElementAnimation()`)
+- `duration` is in milliseconds (default 260); `easing` is one of
+  `LayoutEasing` (`ease`, `ease-in`, `ease-out`, `ease-in-out`, `linear`,
+  `emphasized`; default `ease-out`)
+- A child that is added slides from nowhere: the panel picks it up on its next
+  layout, after it was placed, so only the ones that were already there move
+- Reduced motion: with Windows' animation effects off the attachment does
+  nothing, and it starts when they are turned on
+- It replaces a child's own `implicitAnimations`, and it
+  is not a CSS property: the CSS part has no hook that reaches a Visual's
+  implicit animation collection cheaply, so the attachment is the one way
+- Measured in a window (`test/layout-animation.test.ts`, the
+  `examples/layout-animation` example): 800 ms into a 5 s slide the marker
+  that a growing spacer pushes down is drawn between its two places, and ends
+  in the second
+- `style:translate="0px 60px"` on a component (`<Border style:translate=...>`)
+  works: the same test reads the pixels and finds the control drawn 60 px lower
+  at once, with its layout slot left unchanged
+
+## Settings cards (`winui-svelte/settings`)
+
+The Windows Community Toolkit's `SettingsCard` and `SettingsExpander` are
+managed code with no projectable metadata, so these are built from WinUI's own
+controls (`Border`, `Button`, `Grid`, `FontIcon`, `TextBlock`, `Expander`) and
+the card theme resources (`CardBackgroundFillColorDefaultBrush` and
+`CardStrokeColorDefaultBrush`), so light, dark and high contrast follow Windows
+
+```svelte
+<script lang="ts">
+  import { ToggleSwitch } from "winui-svelte/components";
+  import { SettingsCard, SettingsExpander } from "winui-svelte/settings";
+
+  let isExpanded = $state(false);
+</script>
+
+<SettingsCard description="Start with Windows" header="Run at startup" headerIcon="PowerButton">
+  <ToggleSwitch />
+</SettingsCard>
+<SettingsCard header="Open the logs" isClickEnabled onclick={openLogs} />
+<SettingsExpander header="Appearance" bind:isExpanded>
+  {#snippet items()}
+    <SettingsCard header="Theme">...</SettingsCard>
+  {/snippet}
+</SettingsExpander>
+```
+
+| Prop | Meaning |
+|---|---|
+| `header`, `description` | the name and the line under it |
+| `headerIcon` | a Fluent glyph name or code, or a snippet that draws an icon |
+| children | the control on the right (the toolkit's `Content`) |
+| `isClickEnabled`, `onclick` | the card is a `Button`: focus, Enter and Space, a pressed state |
+| `actionIcon`, `action` | the glyph at the end of a clickable card (default `ChevronRight`), or a snippet that replaces it |
+| `isEnabled`, `automationId` | as on any control |
+| `SettingsExpander`: `isExpanded`, `items` | `bind:isExpanded`; the items are `SettingsCard`s, which draw flat inside |
+
+- Accessibility: a clickable card carries its header as the UI Automation name
+  and its description as the help text, and the expander is named after its
+  header; a card that is not clickable is a plain container whose texts are read
+- Measured in a window (`test/settings-cards.test.ts`, the
+  `examples/settings-cards` example): a card is at least 68 px high, the
+  clickable card is named after its header, the items of a closed expander take
+  no room and show once it is open; the gallery has a `Settings cards` page
+- Not there: the toolkit's `SettingsCard.ContentAlignment`, `IsActionIconVisible`
+  and its automatic wrapping into two rows on a narrow window; the content sits
+  on the right at its own size
+
 ## Connected animation (`winui-svelte/connected-animation`)
 
 `connectElement({ key, element })` remembers an element as the start of a
@@ -310,6 +499,81 @@ connectElement({ key: "photo", element: thumbnail });
 startConnected({ key: "photo", element: hero });
 ```
 
+## Composition animations (`winui-svelte/composition`)
+
+Expression and spring animations that the compositor runs on its own thread,
+typed end to end: an expression is built from typed parts and prints its own
+text, so a member a visual does not have, or an animation of the wrong kind
+for its property, fails `tsc`
+The scroll-linked animations of `animation-timeline` are built with the same
+expression builder
+
+- `visualReference(element)`: an element's visual for expressions to read;
+  its members are `VISUAL_MEMBERS` (`offset`, `scale`, `translation`,
+  `centerPoint` are three-component, `size` and `anchorPoint` two-component,
+  `opacity` and `rotationAngleInDegrees` scalars), and a vector member gives
+  its components (`offset.y`): a member is a `Vector2Member` or
+  `Vector3Member`, the expression of its kind with `x`, `y` (and `z`)
+- An expression is a `ScalarExpression`, `Vector2Expression` or
+  `Vector3Expression`, each with `plus`, `minus` (its own kind, or a plain
+  number, `{ x, y }` or `{ x, y, z }`), `times`, `dividedBy` (a scalar),
+  `negated()` and `lerp({ to, amount })`; a scalar also has
+  `clamped({ min, max })`
+  `scalar(1)`, `vector2({ x, y })` and `vector3({ x, y, z })` make literals,
+  `reference({ name, members, source })` names any Composition object with the
+  members it declares (`ExpressionKind` gives each one's kind)
+- `rawExpression({ kind, text, references })` is the escape hatch: expression
+  text as it is, with the kind it gives and the objects it names
+- `scalarSpring`, `vector2Spring`, `vector3Spring` take `SpringOptions`:
+  `finalValue`, and optionally `initialValue`, `initialVelocity`,
+  `dampingRatio` (below 1 overshoots), `period` and `delay` in milliseconds
+- `animateOnCompositor({ element, property, animation })` starts an expression
+  or a spring on a property of the element's visual (`offset`, `offset.x`,
+  `opacity`...; `translation` is enabled on the element when it is used) and
+  returns a `RunningAnimation`: `stop()`, and `finished`, which settles when a
+  spring comes to rest or the animation is stopped
+  `compositorAnimation({ property, animation })` is the same as an attachment,
+  stopped when the element goes or the attachment runs again
+- `createPropertySet({ element, values })` makes a `CompositionPropertySet`
+  whose members are the keys of `values`, each a number, `{ x, y }` or
+  `{ x, y, z }`: `reference` reads them in expressions, `insert(changes)`
+  writes new values from the UI thread, `animate({ property, animation })`
+  drives one on the compositor, `close()` releases it
+
+```svelte
+<script lang="ts">
+  import type { Border as BorderControl } from "#winui/microsoft/ui/xaml/controls/Border";
+  import { elementRef } from "winui-svelte";
+  import { Border } from "winui-svelte/components";
+  import { compositorAnimation, vector3Spring, visualReference } from "winui-svelte/composition";
+
+  const leader = elementRef<BorderControl>();
+</script>
+
+<Border
+  {@attach compositorAnimation({
+    property: "offset",
+    animation: vector3Spring({ finalValue: { x: 200, y: 0, z: 0 }, dampingRatio: 0.4, period: 80 })
+  })}
+  {@attach leader.attach}
+/>
+{#if leader.current}
+  <Border
+    {@attach compositorAnimation({
+      property: "offset",
+      animation: visualReference(leader.current).offset.plus({ x: 0, y: 120, z: 0 })
+    })}
+  />
+{/if}
+```
+
+- Values read on the UI thread (`Visual.Offset`) are the last ones set there,
+  not the animated ones; read an animated value back from what is drawn
+- Not there yet: `InteractionTracker` (input-driven inertia, which needs a
+  `VisualInteractionSource` redirected from a pointer press and bindings not
+  generated today) and springs as a CSS easing (`transition-timing-function`
+  has no spring function on the web to map)
+
 ## Scheduling (`winui-svelte`)
 
 ```ts
@@ -1090,7 +1354,7 @@ const vertical: Orientation = 1;
 | A path geometry (`GeometryInput`, on `PathIcon` and `Path`) | Path Markup Syntax text or a `Geometry` | `data="M0,0 L10,10"` |
 | A font family (`FontFamilyInput`) | a family name or a `FontFamily` | `"Segoe UI Variable"` |
 | A grid length (`GridLengthInput`) | pixels, or `GridLengthText` as XAML writes it | `"Auto"`, `"2*"`, `"120"` |
-| The package's own | `Backdrop`, `WindowTheme`, `TitleBarHeight`, `WindowPresentation`, `PickerLocation`, `NavigationCacheMode`, `NavigationMode`, `MoveDirection`, `XamlKind`, `FocusKind`, `TrayGesture`, `TrayBalloonIcon` | `backdrop={Backdrop.mica}` |
+| The package's own | `Backdrop`, `WindowTheme`, `TitleBarHeight`, `WindowPresentation`, `PickerLocation`, `NavigationCacheMode`, `NavigationMode`, `MoveDirection`, `XamlKind`, `FocusKind`, `TrayGesture`, `TrayBalloonIcon`, `ConnectedAnimationKind` | `backdrop={Backdrop.mica}` |
 
 A WinUI enum's members keep WinUI's names and case (`"Minimal"`, not
 `"minimal"`), as the metadata and the docs have them; the package's own sets
@@ -1359,6 +1623,63 @@ frame
 `test/web.test.ts` loads one in a real window; it needs an ordinary
 desktop session (a sandboxed process cannot launch the browser, 0x8007139F)
 
+### WebView2 bridge (`winui-svelte/messaging/web-view2`)
+
+A Svelte app and the web content in a `WebView2` talk with the same
+request and response frames as every other transport, over
+`CoreWebView2.PostWebMessageAsJson` and `WebMessageReceived`
+Both are raised on the UI thread, where dynwinrt delivers callbacks
+
+```ts
+import { defineMessaging } from "winui-svelte/messaging";
+import { webView2Transport } from "winui-svelte/messaging/web-view2";
+
+// control is the WebView2 (the sender of oncorewebview2initialized)
+const transport = webView2Transport({ control, allowedOrigins: ["https://app.example"] });
+const bridge = defineMessaging<AppProtocol>({ transport });
+bridge.onMessage("save", ({ data }) => save(data));
+const title = await bridge.sendMessage("title");
+transport.dispose();
+```
+
+```ts
+// in the web page's bundle
+import { createPageTransport, defineMessaging } from "winui-svelte/messaging/page";
+
+const bridge = defineMessaging<AppProtocol>({ transport: createPageTransport() });
+```
+
+- The transport starts the browser (`EnsureCoreWebView2Async`) and waits for
+  it (a control with no `source` does not start on its own, and a page set
+  from `oncorewebview2initialized` can be overtaken by the `source` navigation;
+  the example loads its page from the first `onnavigationcompleted`); frames sent before it is ready are kept and posted in order
+- `dispose()` stops listening, drops the queue and closes the link
+- `window.chrome.webview` is in every page WebView2 loads, so the page needs
+  no injected script; `addDocumentCreatedScript` is for the scripts an app adds
+  of its own
+- Every incoming message is parsed as JSON and checked against
+  `allowedOrigins` (the origin of the page that posted it); a message that
+  fails either is dropped and reported through the listener's `malformed`
+  Without `allowedOrigins` every page is trusted, which suits only content the
+  app ships; a page that is not the app's own needs the list
+- Nothing received is evaluated, and `AreHostObjectsAllowed` is switched off;
+  the bridge never calls `AddHostObjectToScript`
+
+| Helper | What |
+|---|---|
+| `waitForCoreWebView2(control)` | resolves with the `CoreWebView2` once the browser started |
+| `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 |
+| `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 |
+
+`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
+desktop session (a sandboxed process cannot launch the browser, 0x8007139F)
+
 ### ListView and GridView
 
 ```svelte
@@ -1533,9 +1854,26 @@ changes or the window closes)
 `"transparent"` shows the desktop through every pixel the content leaves clear,
 with per-pixel alpha: the window gets a fully clear composition brush behind
 its content (`ICompositionSupportsSystemBackdrop`; the Windows App SDK's
-`TransparentTintBackdrop` is not in the metadata of the releases restored, 2.2
-and 2.3, so it cannot be generated)
+`TransparentTintBackdrop` is in no runtime from 2.3 to 2.6.5 and not in the
+metadata restored, 2.2, so it cannot be generated), and the whole window
+becomes the window manager's frame (`DwmExtendFrameIntoClientArea` with every
+margin -1) with square corners (`DWMWA_WINDOW_CORNER_PREFERENCE` do-not-round),
+which also drops the outline and the shadow Windows 11 draws round a rounded
+window
+Without the frame step the clear pixels read black, not the desktop; it is
+applied again whenever `isBorderless` changes, since WinUI's presenter undoes
+the corner preference
 `window.systemBackdrop` reads null for it
+Measured on Windows 11 build 26300 with the Windows App SDK runtimes 2.3 to
+2.6.5 installed; no other Windows build has been run, and the corner preference
+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
+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
+round the card's own `corner-radius` instead
 Pair it with `isBorderless` and content that sets no background of its own
 A floating card over a transparent window:
 
@@ -1564,6 +1902,18 @@ taking focus
 `onboundschanged` hears the bounds the window opened with and
 then every move or resize (device pixels), so an app that reopens the window
 where it was has them before the user touches it
+`stateKey` keeps the window where its user leaves it: the bounds (the normal
+ones, also while it is maximized), the maximized or minimized state and the
+presentation are saved in `%LOCALAPPDATA%\<app>\window-state\<stateKey>.json`,
+written a moment after each move, resize or state change and again when the
+window closes, and restored before the window first shows
+The restored bounds are kept whole inside the work area of the display nearest
+to them (a display that is gone, or smaller, never leaves the window off
+screen) and are resized to the scale of the display they land on
+On the first run, and when the file is missing, corrupt or from another
+version, `placement` or the centered default applies; a saved place wins over
+`placement`, and a `presentation` prop wins over the saved presentation
+`stateKey` is read once, before the window opens
 `onclosing` runs when the window is asked to close (the close button, Alt+F4,
 `handle.close()`): returning `true` keeps it open (ask the user, then close it
 again from code); `onclosed` follows a close that went through
@@ -1576,6 +1926,10 @@ content's requested theme and the caption buttons'
 `titleBarHeight` is
 `"standard"` or `"tall"` (for a title bar that holds a search box or tabs; it
 applies when the content extends into the title bar)
+`iconShowOptions` is `"showIconAndSystemMenu"` (the default) or
+`"hideIconAndSystemMenu"`: whether the title bar shows the window's icon and
+opens the system menu on a click on it (`AppWindowTitleBar.IconShowOptions`;
+it is set again to the default when the prop is dropped)
 `captionButtons` sets
 the colors of the minimize, maximize and close buttons: `foreground`,
 `background`, `hover*`, `pressed*` and `inactive*` (each `Foreground` or
@@ -1597,7 +1951,9 @@ The size limits and
 `isAlwaysOnTop` are the windowed presentation's, and are set again when the
 window returns to it
 A window that is only its content (a pill, an overlay, a splash screen) is made
-of the frame props: `isBorderless` (no frame, no title bar),
+of the frame props: `isBorderless` (no frame, no title bar; the window keeps its
+8 device pixel resize frame, which shrinks the client area and paints a strip
+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),
@@ -1671,6 +2027,22 @@ device-independent pixels at the window's scale), over `AppWindow.Resize` and
 `AppWindow.Move`
 A process has many windows, so there is no `window` global for them
 
+`handle.windowControlsOverlay` is `navigator.windowControlsOverlay` for the
+window: `visible` (the content extends into the title bar),
+`getTitlebarAreaRect()` (the part of the title bar the content may use, from
+the system's icon to the caption buttons, as `x`, `y`, `width`, `height`,
+`left`, `top`, `right` and `bottom` in CSS pixels, all zeros while `visible`
+is false) and `ongeometrychange` (a `geometrychange` event with
+`titlebarAreaRect` and `visible`, fired when the area or `visible` changes)
+It reads `AppWindowTitleBar.LeftInset`, `RightInset` and `Height` (device
+pixels, divided by the scale) and the client width; the left inset is the
+caption buttons in a right-to-left window
+It follows the window from the first read of the property until the window
+closes, on `AppWindow.Changed` (a size, DPI or presenter change)
+Limits: the CSS `env(titlebar-area-x)`, `titlebar-area-width` and the rest are
+not supported (WinUI has no run-time lengths, so the translator reports them
+as an error); lay the title bar out from `getTitlebarAreaRect()` instead
+
 `owner` (another window's `WindowHandle`) and `isModal`
 (blocks the owner until this window closes) are read once, before the window
 opens; `createWindow` takes them too
@@ -1898,6 +2270,20 @@ The animation target is attached on every timeline: `storyboardTarget`,
 `storyboardTargetName` and `storyboardTargetProperty` call
 `Storyboard.SetTarget`, `SetTargetName` and `SetTargetProperty`
 
+### A refused change
+
+A bound property (`bind:isOn`, `bind:isChecked`, `bind:value` and the rest) is
+two-way: the user's change is written to the bound prop, and the prop's value
+is written to the control
+When the app refuses the change (a function binding whose setter leaves the
+state as it was, or a handler that puts it back) the prop does not change, so
+nothing would write it to the control; after the app has been told, in the next
+Svelte tick, the control is set back to what the prop holds, so a refused
+toggle snaps back with no `await tick()` and no write to the control in the
+handler
+`test/refused-toggle.test.ts` proves it in a window for a `ToggleSwitch` and a
+`CheckBox`
+
 ### Observed state
 
 Read-only state WinUI reports by an event is a bindable prop the control
@@ -2089,7 +2475,7 @@ read and write the file with `node:fs`
 ### App lifecycle (`winui-svelte/app`)
 
 ```ts
-import { ensureSingleInstance, notify } from "winui-svelte/app";
+import { ensureSingleInstance, notify, relaunch, restartAfterCrash } from "winui-svelte/app";
 
 const single = ensureSingleInstance({
   key: "com.example.notes",
@@ -2109,6 +2495,9 @@ notify({
   iconPath: "C:\notes\icon.png",
   appUserModelId: "com.example.notes",
 });
+
+relaunch({ arguments: ["--after-update"], instance: single });
+restartAfterCrash({ arguments: ["--recovered"] });
 ```
 
 An opt-in subpath: an app that does not import it does not bundle it
@@ -2150,6 +2539,192 @@ An opt-in subpath: an app that does not import it does not bundle it
   With package identity (an MSIX or sparse package) it is the supported case
   `ensureSingleInstance` needs no identity: `test/app.test.ts` starts a real
   second copy and checks that the first hears its arguments
+- `activateInstance({ key, activation })` is for a process that is not the
+  app (a tray, a launcher): it sends the same JSON line to the copy that
+  serves `key` and resolves with true, or with false when no copy runs
+  Unlike a later copy it never claims the pipe, so it cannot become the
+  first copy by mistake
+  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
+- `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
+- `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
+  Pass `instance` (the `ensureSingleInstance` result) to release the claim
+  first; otherwise the new copy finds the old one still serving the key and
+  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
+- `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
+  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
+  `RegisterApplicationRecoveryCallback` is not offered); Windows restarts
+  only an app that ran for 60 seconds; after a crash or a hang the user is
+  offered the restart, and only after an update is it automatic; a normal
+  exit is never restarted; a command line too long for Windows throws
+  `test/app.test.ts` checks the registration and that a normal exit starts
+  nothing, and `relaunch` with a real second process (no crash is caused)
+
+### Activation (`winui-svelte/app/activation`)
+
+Starting the app from a link, a file or sign-in, without an installer
+An opt-in subpath: an app that does not import it does not bundle it, and
+nothing is written to Windows until a registration function is called
+
+```ts
+import {
+  ActivationKind,
+  installProtocolHandlers,
+  launchAtLogin,
+  registerFileTypes,
+  startActivation,
+} from "winui-svelte/app/activation";
+
+installProtocolHandlers();
+navigator.registerProtocolHandler("note", "https://notes.example/open?uri=%s");
+registerFileTypes({ id: "com.example.notes", extensions: [".note"] });
+launchAtLogin({ id: "com.example.notes", isEnabled: true });
+
+const single = startActivation({
+  key: "com.example.notes",
+  window: mainWindow,
+  extensions: [".note"],
+  onActivation(event) {
+    if (event.kind === ActivationKind.protocol) open(new URL(event.uri));
+    if (event.kind === ActivationKind.file) openFiles(event.files);
+  },
+});
+if (!single.isPrimary) {
+  exitApplication();
+}
+```
+
+| Web API or extra | Windows | Notes |
+|---|---|---|
+| `navigator.registerProtocolHandler(scheme, url)` | `HKCU\Software\Classes\<scheme>` with `URL Protocol` and `shell\open\command` | `url` must hold `%s` (`SyntaxError` otherwise) and is not used further: the handler is always this app |
+| `navigator.unregisterProtocolHandler(scheme, url)` | deletes that key | only a key the package wrote; another program's is left alone |
+| `registerFileTypes({ id, extensions, description })` | a ProgID `<id><extension>` and the extension's `OpenWithProgids` | the app is listed in Open with; the default stays the user's choice |
+| `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 |
+| `startActivation({ key, onActivation })` | `ensureSingleInstance` and the command line | one `ActivationEvent` per start or redirect |
+
+- `ActivationEvent` is a union on `kind` (`ActivationKind`, also from
+  `winui-svelte/enums`): `launch` (started by hand), `file` (`files`, absolute
+  paths of existing files), `protocol` (`uri`, `scheme`), `startup` (started
+  at sign-in) and `redirect` (a later copy with nothing to open)
+  Every event has `isRedirect`, `arguments` and `workingDirectory`; a link
+  sent by a later copy is `protocol` with `isRedirect: true`
+- A link wins over files, files win over the startup marker; an argument
+  that fits none stays in `arguments`
+  Arguments are checked with a schema (up to 1024 of them, up to 32767
+  characters each, no NUL); a failure goes to `onError`, the rest go on
+- Events arrive in order, one at a time, in the first copy; the later copy
+  gets `isPrimary: false` and exits
+  Redirects are also handed to `launchQueue.enqueueActivation` when you pass
+  `launchQueue`; the first start's command line reaches `launchQueue` through
+  `installLaunch`
+- The command Windows runs is this process's `node.exe`, its flags and its
+  entry script, then `"%1"`; pass `command: { program, arguments }` for a
+  bundled executable
+  The Windows App SDK's `ActivationRegistrationManager` takes an executable path
+  and no arguments, so for `node.exe` it cannot name the script; the registry route is the one it writes underneath, and needs
+  no package identity
+- Security: only `HKEY_CURRENT_USER` is ever opened, never
+  `HKEY_LOCAL_MACHINE`
+  Schemes follow RFC 3986 (a letter, then letters, digits, `+`, `-` and `.`,
+  two characters or more) and `http`, `https`, `file`, `ftp`, `mailto`, `ms-*`
+  and the other system and browser schemes are a `SecurityError`; so are
+  extensions that run code (`.exe`, `.bat`, `.js`, `.lnk` and so on)
+  Every key the package creates carries a `WinuiSvelte` value, and it
+  overwrites or deletes only keys that carry it; a scheme or ProgID that
+  another program owns is an `InvalidStateError`
+  A received link is data: it is validated (no control characters, 8192
+  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
+- 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`
+- `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
+
+### Global hotkeys (`winui-svelte/app/hotkeys`)
+
+A system-wide key combination, heard whichever app has the focus
+A web page cannot own a global key, so there is no web API to mirror; the
+callback is told a `KeyboardEvent`-like object and the prop is the lowercase
+`onpressed`
+An opt-in subpath: an app that does not import it does not bundle it
+
+```ts
+import { registerHotkey } from "winui-svelte/app/hotkeys";
+
+const hotkey = registerHotkey({
+  keys: "ctrl+alt+k",
+  onpressed: ({ keys }) => togglePalette(),
+});
+// later: hotkey.isRegistered, hotkey.unregister()
+```
+
+- `keys` is a string of modifiers and one key joined by `+`, in any case
+  (`ctrl+alt+k`, `win+shift+f23`, `ctrl+5`, `f9`), or a typed object
+  `{ modifiers: [HotkeyModifier.control], key: "k" }`
+  Modifiers: `ctrl`/`control`, `alt`/`option`, `shift`, `win`/`windows`/`meta`/`super`
+  Keys are named as `KeyboardEvent.code` names them, lowercase: letters,
+  `digit0` to `digit9` (a bare `5` works in a string), `f1` to `f24`, `numpad0`
+  to `numpad9`, `arrowleft`, `escape`, `space`, `minus`, `equal`,
+  `bracketleft`, the media and volume keys
+  `KeyCode` (in `winui-svelte/enums`, spelled as `KeyboardEvent.code` is) is the
+  table every key name maps from to its virtual-key code, the same one the
+  input events name keys with, and `HotkeyModifier` holds the modifiers
+  A few aliases are accepted in a string (`esc`, `del`, `left`, `pgup`)
+  A modifier named twice, no key, two keys or an unknown name throws
+  `HotkeyParseError`
+- `onpressed` runs on the UI thread with `{ keys, key, modifiers, ctrlKey,
+  altKey, shiftKey, metaKey }`; holding the keys down presses once, because
+  `MOD_NOREPEAT` is the default (`isRepeatAllowed: true` lifts it)
+  An error thrown by the callback goes to `onUiError` and the hotkey stays
+- Failures are typed and all extend `HotkeyError`: `HotkeyConflictError` when
+  another app (or this one) owns the combination
+  (`ERROR_HOTKEY_ALREADY_REGISTERED`), `HotkeyRefusedError` (with `code`) when
+  Windows refuses it, `HotkeyParseError` for the string
+- `unregister()` gives the combination back and may be called twice
+  In a component, register in an `$effect` and return the unregister, so a
+  closed window releases it; Windows frees the rest when the thread ends
+- How it works: `RegisterHotKey` with no window posts `WM_HOTKEY` to the
+  registering thread's queue, where no window procedure ever sees it
+  The message pump (`createMessageSource`) offers each message it takes to a
+  short list of hooks (`src/window/message-hooks.ts`) before the content and
+  `DispatchMessage`, and the hotkey registry is one hook
+  Any thread that runs the package's pump hears the hotkeys registered on it,
+  a tray-only app with no window included; the registry and the hook list are
+  one per thread
+- Limits:
+  - Nothing is heard while the pump is not running (before `runWindow` has
+    started it, or after it stopped), and a callback waits for the message in
+    front of it
+  - Register on the thread whose pump runs, the UI thread
+  - Windows reserves some combinations (`win+l`, `ctrl+alt+delete`, and others
+    the shell owns): they throw `HotkeyRefusedError` or `HotkeyConflictError`
+  - The first app to register a combination owns it; the only way to know is
+    to try, and to ask the user for another when it throws
+  - A key with no modifier (`f9`) is taken from every app
+- `test/hotkeys.test.ts` registers `ctrl+alt+shift+f23` in a real window and
+  posts `WM_HOTKEY` to the thread itself with `PostThreadMessageW`; no key is
+  pressed
 
 ### System tray (`winui-svelte/tray`)
 
@@ -2272,6 +2847,147 @@ window's content
 A Tauri or Electron host that already has a tray should keep it: two icons
 would show, and this one lives and dies with the WinUI window's process
 
+### Tray with no window (`winui-svelte/tray/standalone`)
+
+A tray that runs in a process of its own, plain Node, with no `Window`, no
+app, no WinUI and none of the component barrel: the notification-area icon
+and its menu, and a click that starts or signals the full app
+The panel then opens only when the user asks, and between clicks the tray
+holds a fraction of the memory
+`winui-svelte/tray` cannot do this: its `TrayIcon` mounts a WinUI window
+for the menu and its timers run on the dispatcher queue
+
+```ts
+import {
+  activateOrLaunch,
+  createStandaloneTray,
+  NativeMenuEntryKind
+} from "winui-svelte/tray/standalone";
+
+function openPanel() {
+  void activateOrLaunch({
+    key: "com.example.panel",
+    activation: { arguments: ["--show"], workingDirectory: process.cwd() },
+    launch: { command: "C:\\Program Files\\Panel\\panel.exe", arguments: ["--show"] }
+  });
+}
+
+createStandaloneTray({
+  icon: "tray.ico",
+  tooltip: "Panel",
+  onclick: openPanel,
+  menu: [
+    { kind: NativeMenuEntryKind.COMMAND, label: "Open", onselect: openPanel },
+    { kind: NativeMenuEntryKind.SEPARATOR },
+    { kind: NativeMenuEntryKind.COMMAND, label: "Quit", onselect: () => process.exit(0) }
+  ]
+});
+```
+
+- `createStandaloneTray(options)` takes the icon's options (`icon`,
+  `tooltip`, `isVisible`, `guid`, `onclick`, `ondoubleclick`,
+  `onmiddleclick`) and `menu`, and returns the same handle as
+  `createTrayIcon` (`update`, `notify`, `bounds`, `isRegistered`, `remove`)
+  The icon keeps the process alive; `remove()` or the process ending takes it
+  out of the tray
+- The menu is Windows' own popup menu (`TrackPopupMenuEx`), made on a right
+  click and destroyed when it closes; nothing of it exists while idle
+  A command is `{ kind, label, onselect, isEnabled }`, a line is
+  `{ kind: NativeMenuEntryKind.SEPARATOR }`
+  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
+  `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
+  one place; the app side calls `ensureSingleInstance` with the same `key`
+- The clicks are heard the way `winui-svelte/tray` hears them, by polling
+  the pointer on the process's timer (Node's `setInterval`)
+- A test bundles it (`scripts/pack/tray-only.test.ts`) and fails if any
+  component, window or renderer module, or a component's name, is in the
+  output, or if it grows past its budget
+
+### Notice with no app (`winui-svelte/notice`)
+
+`showNotice` shows a message box before there is a window or an app: the
+checks that end a run before it starts (the Windows 11 gate, a revoked
+licence) can tell the user why
+
+```ts
+import { NoticeButton, NoticeButtons, NoticeIcon, showNotice } from "winui-svelte/notice";
+
+await showNotice({
+  title: "My app",
+  message: "This app needs Windows 11",
+  icon: NoticeIcon.ERROR
+});
+const pressed = await showNotice({
+  title: "Update",
+  message: "Install now?",
+  icon: NoticeIcon.QUESTION,
+  buttons: NoticeButtons.YES_NO
+});
+const isConfirmed = pressed === NoticeButton.YES;
+```
+
+- `showNotice({ title, message, icon, buttons, owner })` resolves with the
+  `NoticeButton` pressed: `ok`, `cancel`, `yes`, `no`, `retry`, `abort` or
+  `ignore`
+  `icon` is a `NoticeIcon` (`none`, `information`, `warning`, `error`,
+  `question`), `buttons` a `NoticeButtons` (`ok`, `okCancel`, `yesNo`,
+  `yesNoCancel`, `retryCancel`, `abortRetryIgnore`)
+- It is `MessageBoxW` and nothing else: no WinUI, no `runWindow`, no
+  `initWindowsAppSdk`, so plain Node can call it first thing
+  Without an `owner` the box stays on top and takes the foreground;
+  `owner` is a window handle to center on and block
+- It is not a TaskDialog: `TaskDialogIndirect` needs Common Controls 6, which
+  `node.exe` has no manifest for, so custom button text, links and progress
+  bars are not here
+- The dialog is modal and runs its own message loop, so the calling thread
+  waits for it
+  It throws when Windows could not show the box
+  A box cannot be dismissed from a test without input, so the tests fake the
+  call; the one real call they make passes a window handle that does not
+  exist, which Windows refuses at once without showing anything
+### Taskbar button (`winui-svelte/window/taskbar`)
+
+`handle.taskbar` is the window's button on the taskbar: a progress bar, an
+overlay icon and flashing, over `ITaskbarList3` and `FlashWindowEx`
+No package identity is needed; call it on the UI thread
+The shell calls need the real desktop shell, so a window on a desktop of its
+own gets `E_NOTIMPL`; a window that has no taskbar button (a background or
+tray window) accepts the calls and shows nothing
+
+```ts
+import { TaskbarProgressState } from "winui-svelte/window/taskbar";
+
+handle.taskbar.setProgress({ state: TaskbarProgressState.NORMAL, value: 0.4 });
+handle.taskbar.setOverlayBadge({ count: 3 });
+handle.taskbar.flash({ count: 2 });
+```
+
+- `setProgress({ state, value })`: `state` is a `TaskbarProgressState`
+  (`none`, `indeterminate`, `normal`, `error`, `paused`); `value` is 0 to 1,
+  clamped, and ignored for `none` and `indeterminate`; a value that is not a
+  number is a `TypeError`
+- `setOverlayIcon({ icon, description })`: `icon` is the path of an .ico file
+  or `null` to remove it; `description` is what a screen reader says
+- `setOverlayBadge({ count })` or `setOverlayBadge({ glyph })`: draws the badge
+  as pixels (a disc with the digits, or the `BadgeGlyph`'s colour and mark) at
+  the system's small icon size; `clearOverlay()` takes any overlay away
+- `flash({ count, until })`: `until` is a `TaskbarFlashUntil` (`count`, the
+  default, flashes `count` times, 3 by default; `foreground` until the window is
+  brought forward; `stopped` until `stopFlashing()`)
+- `createTaskbarButton(hwnd)` and `TaskbarButton` take a window handle
+  (`appWindow.id.value`) directly; `taskbarBadgeBackend(button)` is the
+  `fallback` for `installBadging`
+- `examples/taskbar`: a download bar mirrored on the button and an unread count
+- `ITaskbarList3` has no WinRT form, so its methods are declared by hand at
+  their vtable slots over dynwinrt's `DynComUnsafe`, as the share interop is
+- The shell offers no way to read a bar or an overlay back, so the window test
+  (`test/taskbar.test.ts`, on the default desktop with an off-screen window)
+  checks that every call returns `S_OK`
+
 ### Localization: what works unpackaged
 
 - **`Intl` and your own string tables work everywhere.**
@@ -2491,6 +3207,127 @@ 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
 
+## Input events and focus (`winui-svelte/input`)
+
+The web's pointer, wheel, keyboard and focus events on any element, and focus
+management, over `Microsoft.UI.Xaml.Input`
+Opt-in: nothing is bundled until an app imports it, and importing does no work
+Everything runs on the UI thread
+
+### Events as on the web
+
+```svelte
+<script lang="ts">
+  import { enableInputEvents, setPointerCapture, PointerType } from "winui-svelte/input";
+  import type { KeyboardEvent, PointerEvent } from "winui-svelte/input";
+
+  enableInputEvents();   // once, before the first window
+</script>
+
+<border
+  onpointerdown={(event: PointerEvent) => {
+    setPointerCapture({ control: event.currentTarget, pointerId: event.pointerId });
+    const isPen = event.pointerType === PointerType.pen;
+    console.log(event.clientX, event.clientY, isPen ? event.pressure : 1);
+  }}
+  onpointermove={(event: PointerEvent) => {
+    for (const point of event.getCoalescedEvents()) {
+      console.log(point.x, point.y);
+    }
+  }}
+  onkeydown={(event: KeyboardEvent) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+    }
+  }}
+>
+  <text-block>Draw here</text-block>
+</border>
+```
+
+`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
+A WinUI-named event on the same element (`onpointerpressed`) keeps WinUI's own
+arguments, and so does every component prop: components get no new props
+`onkeydown` is the one name both share; on a raw element it takes the web's
+`KeyboardEvent` once the events are enabled
+
+| Web event | WinUI | Notes |
+|---|---|---|
+| `pointerdown`, `pointerup`, `pointermove` | `PointerPressed`, `PointerReleased`, `PointerMoved` | `pointerId`, `pointerType` (`PointerType.mouse`, `pen`, `touch`; a touchpad is a mouse), `isPrimary`, `pressure`, `tiltX`, `tiltY`, `twist`, `button`, `buttons`, `clientX`, `clientY` (also `offsetX`, `pageX`, `x`), the four modifiers |
+| `pointerenter`, `pointerleave` | `PointerEntered`, `PointerExited` | WinUI bubbles them, the web does not |
+| `pointercancel` | `PointerCanceled` | |
+| `wheel` | `PointerWheelChanged` | `deltaX`, `deltaY` (positive when the wheel turns toward the user), `deltaMode` (always 0, pixels; WinUI gives 120 per notch) |
+| `keydown`, `keyup` | `KeyDown`, `KeyUp` | `key` and `code` mapped from `VirtualKey`, `repeat`, the modifiers read from the keyboard state |
+| `focusin`, `focusout` | `GotFocus`, `LostFocus` | `target`, `currentTarget`; no `relatedTarget` |
+
+`event.getCoalescedEvents()` lists the points the pointer passed since the last
+event, oldest first, as plain field objects (`x`, `y`, `pressure` and the rest)
+`event.preventDefault()` and `stopPropagation()` both mark the WinUI event
+handled, so it goes no further up the tree and the control skips its own
+handling (a handled `keydown` for Tab does not move focus)
+`event.target` is `originalSource` (the element the event started at) and
+`event.currentTarget` the element the handler is written on
+
+Limits:
+
+- `key` and `code` assume the US layout, because WinUI's `VirtualKey` has no
+  punctuation keys (they are `Unidentified`) and Shift does not turn `1` into
+  `!`; read text from a `TextBox`, not from `keydown`
+- `isComposing` is always false: WinUI sends input method text to the text
+  controls, not to `KeyDown`
+- `mouse*` and `click` are not provided; use the pointer names, or the
+  `click` prop of a component
+- `getCoalescedEvents` entries are field objects, not full events
+
+### Pointer capture
+
+```ts
+setPointerCapture({ control, pointerId });     // returns true when WinUI took it
+hasPointerCapture({ control, pointerId });
+releasePointerCapture({ control, pointerId });
+```
+
+WinUI captures a `Pointer` object where the web captures an id, so the element
+remembers every pointer its input events carried; capturing an id that has not
+reached the element yet throws
+Call it from a `pointerdown` handler, as on the web
+
+The Canvas 2D of `winui-svelte/win2d/context-2d` reads the same fields (one
+implementation), so a drawing library on a canvas sees the same `pointerType`,
+`pressure`, tilt and coalesced events
+
+### Focus
+
+```svelte
+<script lang="ts">
+  import { activeElement, moveFocus, trapFocus } from "winui-svelte/input";
+  import { FocusNavigationDirection } from "winui-svelte/enums";
+
+  const active = activeElement();   // active.current: the focused FrameworkElement or null
+</script>
+
+<StackPanel {@attach trapFocus()}>
+  <Button onclick={sender => moveFocus({ direction: FocusNavigationDirection.Down, within: sender })}>
+    Down
+  </Button>
+</StackPanel>
+```
+
+| API | Web | Notes |
+|---|---|---|
+| `activeElement().current` | `document.activeElement` | reactive; kept by `FocusManager`'s `GotFocus` and `LostFocus`, so it is null until focus first moves after the call; call it while a component initialises |
+| `moveFocus({ direction, within })` | none | `Up`, `Down`, `Left`, `Right` over XY focus navigation; `within` is any loaded element of the window; WinUI refuses `Next` and `Previous` in a desktop app, so those throw |
+| `trapFocus({ shouldFocusFirst })` | a focus trap | an attachment: sets `TabFocusNavigation` to `Cycle` (Tab after the last control goes to the first, Shift+Tab before the first to the last), moves focus in when the element is shown, gives it back to where it was when the element goes |
+| `FocusNavigationDirection` | none | in `winui-svelte/enums` |
+| `focusElement` | `element.focus()` | in `winui-svelte`, see Reactive readers of an element |
+
+`FocusManager.GetFocusedElement()` without a window returns nothing in a desktop
+app, which is why `moveFocus` takes `within` and `trapFocus` reads the focus by
+the element's own window
+A trap cannot stop focus leaving through the title bar or another window
+
 ## Web APIs (`winui-svelte/web-apis`)
 
 The standard Web APIs over WinRT and Win32, installed on demand; the package
@@ -2522,6 +3359,8 @@ needs
 | `requestAnimationFrame`, `requestIdleCallback` | `winui-svelte/web-apis/timing` | web | none | done |
 | `ResizeObserver`, `IntersectionObserver`, `MutationObserver` | `winui-svelte/web-apis/observers` | web plus extras | none | done |
 | `element.animate()`, `Animation`, `KeyframeEffect` | `winui-svelte/web-apis/animations` | web plus extras | none | done |
+| `ScrollTimeline`, `ViewTimeline`, `element.animate(keyframes, { timeline })` | `winui-svelte/scroll-timeline` | web | none | done |
+| `document.startViewTransition`, `ViewTransition`, `view-transition-name` | `winui-svelte/view-transitions` | web plus extras | none | done |
 | `navigator.mediaDevices` (`getUserMedia`, `getDisplayMedia`, `enumerateDevices`), `MediaStream`, `MediaRecorder` | `winui-svelte/web-apis/media-devices` | web plus extras | none (a camera or microphone needs the Windows privacy switch on) | done |
 | `speechSynthesis`, `SpeechSynthesisUtterance`, `SpeechRecognition` (SSML, silences, scenario, phrases) | `winui-svelte/web-apis/speech` | web plus extras | none | done |
 | `navigator.mediaSession`, `MediaMetadata` | `winui-svelte/web-apis/media-session` | web plus extras | none | done |
@@ -2533,6 +3372,7 @@ needs
 | `IdleDetector` (user and screen state) | `winui-svelte/web-apis/idle` | web plus extras | none | done |
 | `navigator.credentials`, `PasswordCredential`, `PublicKeyCredential` (Windows Hello) | `winui-svelte/web-apis/credentials` | web plus extras | none | done |
 | `EyeDropper` | `winui-svelte/web-apis/eye-dropper` | web plus extras | none | done |
+| `FontFace`, `document.fonts` (font files of the app) | `winui-svelte/web-apis/fonts` | web plus extras | none | done |
 | `navigator.contacts` (Contact Picker) | `winui-svelte/web-apis/contacts` | web plus extras | for most apps, package identity | done |
 
 Every row is built and tested; the timers (`setTimeout`, `setInterval`,
@@ -2613,6 +3453,23 @@ with `registerPermission({ name, provider })` and calls
   `incomingCall`, `urgent`), `expiration`, `group`, `hero`, `audio` (`default`,
   `im`, `mail`, `reminder`, `sms`, `alarm` to `alarm10`, `call` to `call10`),
   `attribution`
+- Listing and clearing: `notificationRegistration().getNotifications({ tag })`
+  (`NotificationRegistration`, the notification members of a `ServiceWorkerRegistration`, which has no
+  service worker here) lists what this run showed and Windows still holds
+  (`AppNotificationManager.GetAllAsync`), so one the user dismissed in the
+  notification center is not listed; one an earlier run showed has no object
+  to return and is not listed; `Notification.closeAll()` (WinUI-only) closes
+  the ones this run holds and calls `RemoveAllAsync`, which clears the earlier
+  run's as well
+- Scheduling: `showTrigger: new TimestampTrigger(Date.now() + 60_000)` shows
+  the notification at that moment, even after the app has exited
+  (`Windows.UI.Notifications`' `ScheduledToastNotification`, built from the
+  same toast XML; the App SDK manager has no schedule); only a process with
+  package identity can schedule, and without it the constructor throws
+  `NotSupportedError`; a scheduled notification fires no `show`, and
+  `close()` before the moment takes it out of the schedule; not exercised for
+  real here (`node.exe` has no identity), so the tests cover it with a fake
+  backend
 - Package identity: not needed to show; an unpackaged app registers with
   `identity` (name and icon file) and `appUserModelId`; the `urgent` scenario
   and tooltips need a recent Windows build; a click after the process has gone
@@ -2646,8 +3503,11 @@ silent failure
   count is a `TypeError`
   WinUI-only: `navigator.setAppBadgeGlyph(glyph)` with a `BadgeGlyph`
   (`alert`, `available`, `away`, `busy`, `newMessage` and so on)
-  The unpackaged fallback (an overlay icon through `ITaskbarList3`) is not
-  built; without identity Windows refuses and the call rejects
+  Without identity Windows refuses and the call rejects, unless
+  `installBadging({ fallback: taskbarBadgeBackend(handle.taskbar) })` is given:
+  the badge is then drawn as an overlay icon on that window's taskbar button
+  (a red disc with the count, 99+ above 99, or the glyph's colour and mark),
+  see "Taskbar button"
 - `installLaunch({ initialArguments })` defines `launchQueue` (a `LaunchQueue`) with `setConsumer`
   The start's command line is the first launch; each later copy's is handed
   over with `launchQueue.enqueueActivation(activation)` (WinUI-only), which
@@ -2655,7 +3515,7 @@ silent failure
   `LaunchParams.targetURL` is the first `scheme:` argument, `files` are the
   existing paths, as the file-system API's own `FileSystemFileHandle` (`name`, `getFile()`, the WinUI-only `path`)
   Launches wait for the consumer; registering the protocol or file type with
-  Windows is the installer's job
+  Windows is `winui-svelte/app/activation`'s job (see Activation)
 
 ### Location and device state
 
@@ -2864,8 +3724,16 @@ called (`runWindow({ webApis: [installPage, installTiming] })`)
 that `usePageWindow(handle)` is given (`bind:handle` on `<Window>`)
 
 - `document.visibilityState`, `hidden`, `hasFocus()` and `visibilitychange`:
-  hidden means minimized or hidden (to the tray); the window being active is
-  focus
+  hidden means minimized, hidden (to the tray) or the display turned off; the
+  window being active is focus
+- `document` `freeze` and `resume` (Page Lifecycle, with `onfreeze` and
+  `onresume`): once per wake of the machine from sleep, `freeze` then
+  `resume` together, because a sleeping process cannot see itself go to sleep;
+  the wake is found by a gap of over ten seconds between two ticks of a
+  one-second timer, so it is also counted after a long stall of the process;
+  never exercised with a real sleep here (the tests use a stand-in clock)
+- The display and the wake come from `windowsSystemPowerSource` (see Devices,
+  power); a machine where it cannot be read counts as awake with the display on
 - `window` `focus`, `blur`, `beforeunload` (call `preventDefault()` to keep the
   window open; there is no prompt), `pagehide` and `unload`, with `onfocus` and
   the other handler properties; `window.close()`, `window.closed` and
@@ -2935,13 +3803,107 @@ tree's elements `animate()` and `getAnimations()`, and the global scope
   rotation, size, margin, padding, border, shape dashes); the keyframes are
   evenly spaced, so a keyframe `offset` or `easing` is ignored, and anything
   else warns once
-- Not covered: `document.getAnimations()`, composite modes, pseudo-elements and
-  scroll timelines
+- Not covered: `document.getAnimations()`, composite modes and
+  pseudo-elements; scroll timelines are `winui-svelte/scroll-timeline`, below
 - Extras (WinUI only): `element.prepareConnectedAnimation(key)` and
   `element.startConnectedAnimation(key)` over `ConnectedAnimationService`;
   implicit animations are the CSS `transition:` the translator already maps to
   `OpacityTransition` and its siblings
 
+#### Scroll timelines (`winui-svelte/scroll-timeline`)
+
+`installScrollTimeline()` defines `ScrollTimeline` and `ViewTimeline` on the
+global scope and lets `element.animate(keyframes, { timeline })` follow a scroll
+position instead of the clock; install `installAnimations()` first for the rest
+of the Web Animations API (a call without a timeline goes on to it)
+It is not part of `installWebApis`; `"ScrollTimeline" in globalThis` tells
+whether it was installed
+
+- `new ScrollTimeline({ source, axis })`: `source` is a `<scroll-viewer>`
+  element, `axis` is `block` (the default), `inline`, `x` or `y`;
+  `currentTime` is `{ value, unit: "percent" }` of the scrollable range, or
+  `null` while the source is no scroll viewer in a window, and `duration` is 100
+  percent
+- `new ViewTimeline({ subject, axis, inset })`: `currentTime` is how far the
+  subject has crossed the nearest scroll viewer, from entering (0) to leaving
+  (100); `inset` is `"10px"` or `["10px", "20%"]`
+- `element.animate(keyframes, { timeline, rangeStart, rangeEnd, direction })`
+  returns a `ScrollLinkedAnimation` with `timeline`, `playState`
+  (`running` or `idle`) and `cancel()`; `rangeStart` and `rangeEnd` are the
+  CSS `animation-range` words (`"entry 10%"`, `"25%"`)
+- The same rules as the CSS: the keyframes go through the CSS build's reader,
+  so opacity, translate, scale, rotate and a transform of them work, and a
+  width, a color, a keyword or a skew is a `NotSupportedError`, as is an easing
+  other than `linear` and an iteration count other than 1; a keyframe `offset`
+  is honoured, the rest are evenly spaced
+- Under reduced motion (Windows' animation effects off, or the
+  `isMotionReduced` option) the animation does not start and `playState` is
+  `idle`; an element with the class `winui-motion-always` keeps it
+- The compositor runs the animation, so the UI thread cannot read its value
+  back: `Visual.Opacity` stays at its resting value (the pixels are what shows)
+- Not covered: `getAnimations()` for these, `pause()`, `play()` and
+  `currentTime` of the animation, and `timeline-scope`
+
+#### View transitions (`winui-svelte/view-transitions`)
+
+`installViewTransitions()` defines `document.startViewTransition` and
+`ViewTransition` over WinUI's connected animations
+An element takes part through `view-transition-name` in a sheet or a style
+attribute (`winui-svelte/css/view-transition`, see `src/css/API.md`): before
+the update runs, each named element is prepared under its name
+(`ConnectedAnimationService.PrepareToAnimate`); after it, the element with the
+same name starts that animation (`TryStart`), and WinUI flies a picture of the
+old element to the new one
+
+```svelte
+<script lang="ts">
+  import { installViewTransitions } from "winui-svelte/view-transitions";
+
+  installViewTransitions();
+  let selected = $state<Photo | null>(null);
+
+  function open(photo: Photo) {
+    document.startViewTransition(() => {
+      selected = photo;
+    });
+  }
+</script>
+
+{#if selected}
+  <border class="hero" style="view-transition-name: photo-{selected.id}" />
+{:else}
+  {#each photos as photo (photo.id)}
+    <border style="view-transition-name: photo-{photo.id}" />
+  {/each}
+{/if}
+```
+
+- `startViewTransition(update)` or `startViewTransition({ update, types })`
+  returns a `ViewTransition` with `updateCallbackDone`, `ready`, `finished`,
+  `types` and `skipTransition()`; the update may return a promise, and runs in
+  a microtask after the old elements are prepared
+- After the update the transition waits one turn of the event loop for Svelte
+  to apply it, then pairs the names; `ready` resolves once the animations
+  start, `finished` once WinUI reports each one completed
+- Like the web: a name two elements share skips the transition (`ready`
+  rejects with an `InvalidStateError`), `skipTransition()` rejects `ready`
+  with an `AbortError` and lets `finished` follow the update, an update that
+  throws rejects all three promises with its error, and a new transition skips
+  the one still running
+- Extras (WinUI only): `configuration` in the options object picks the
+  motion, a `ConnectedAnimationKind` from `winui-svelte/enums`: `gravity`
+  (WinUI's default, for going forward), `direct` (for going back) or `basic`
+- Limits: only a name both states have moves; a name only the old state has
+  gets no exit and one only the new state has no entrance (the web would fade
+  them), and there is no cross-fade of the whole window (the web's `root`)
+  An element that keeps its name and stays in the tree does not move: WinUI
+  will not animate an element to itself (`implicitLayoutAnimation` slides
+  children the layout moves)
+  The duration and easing are WinUI's (`ConnectedAnimationService`), not CSS;
+  the `::view-transition-*` pseudo-elements, `view-transition-class` and
+  `:active-view-transition-type()` have no counterpart, and `types` is carried
+  but read by nothing
+
 ### Media devices (`winui-svelte/web-apis/media-devices`)
 
 `installMediaDevices()` defines `navigator.mediaDevices` (`enumerateDevices`,
@@ -3188,6 +4150,35 @@ needs a single-threaded apartment: the window thread has one)
   `unlocked`) set; `change` fires when either moves
 - Extra: `idleMilliseconds`, the time since the last input at the last reading
 
+#### Fonts
+
+`installFontFaces()` defines `FontFace` and `document.fonts` (a `FontFaceSet`)
+over the font registry that a stylesheet's `@font-face` also fills, so a font
+file of the app is used by its family name in a `font-family` of a style and in
+a `fontFamily` prop
+
+- `new FontFace(family, source, descriptors)`: `source` is `url("...")`, a path
+  or a `file:` URL (a relative path is relative to the working folder), or the
+  bytes of a font (written to a file of the temporary folder named by their
+  hash); `load()` registers the file under the family and rejects with
+  `NetworkError` when there is no such file; `status` and `loaded` follow
+- `document.fonts.add(face)` registers at once; `delete(face)`, `clear()` and
+  `has(face)` as on the web; `check(font)` and `load(font)` look at the faces of
+  the set that the font shorthand names; `ready` is resolved and `status` is
+  `loaded`
+- `FontLoadStatus` is the closed set of `status` (`"unloaded"`, `"loading"`,
+  `"loaded"`, `"error"`)
+- The family must be the name written inside the font file; weight, style,
+  width and `unicodeRange` are kept and read back but choose nothing, because
+  WinUI takes the face from the file
+- WinUI cannot unload a font: after `delete(face)` the family stops being
+  spelled as its file, but a font already loaded stays usable by name until the
+  process ends
+- It works in a plain Node process; nothing is installed on the machine (the
+  file is handed to WinUI as `ms-appx:///` and its absolute path)
+- Extra: `registerFont({ family, source, base })` and `unregisterFont(family)`
+  from `winui-svelte/css`, the registry itself
+
 #### Other exports
 
 - Bluetooth: `BluetoothRemoteGATTServer`, `BluetoothRemoteGATTService`,
@@ -3276,6 +4267,82 @@ the five properties
 - `ContactChooser` is the one interface the real picker (`windowsContactChooser`)
   and the tests implement
 
+## Accessibility (`winui-svelte/accessibility`)
+
+Tell a screen reader what happened, and check the window for what it would
+trip on; each is opt-in, and the audit is for development only
+
+```svelte
+<script lang="ts">
+  import { announce, LivePriority, liveRegion } from "winui-svelte/accessibility";
+  import { elementRef } from "winui-svelte";
+  import { TextBlock } from "winui-svelte/components";
+
+  const status = elementRef<TextBlock>();
+</script>
+
+<!-- a live region: a change of its text is spoken -->
+<TextBlock {@attach liveRegion({ priority: LivePriority.POLITE })} {@attach status.attach}>{saved}</TextBlock>
+```
+
+```ts
+announce({ message: "Saved", element: status.current, priority: LivePriority.POLITE });
+```
+
+| Web API | Here |
+|---|---|
+| `aria-live="polite"` and `role="status"` | `LivePriority.POLITE`: waits for the user, a newer message replaces an older one |
+| `aria-live="assertive"` and `role="alert"` | `LivePriority.ASSERTIVE`: interrupts |
+| `aria-live="off"` | `LivePriority.OFF`: says nothing |
+| writing text into a live region | `announce({ message, element, priority })`: `AutomationPeer.RaiseNotificationEvent` (kind Other; polite is `MostRecent`, assertive is `ImportantMostRecent`) |
+| the `aria-live` attribute | `liveRegion({ priority })`: `AutomationProperties.LiveSetting` of the element |
+
+- `FormField` marks its error text with the same `liveRegion`, so a form error
+  is spoken when it appears
+- `announce` raises the notification from `element`, or from the nearest
+  element above it that has an automation peer (a layout panel has none; a
+  `TextBlock` does), so keep a small status element for it
+- `LivePriority` is also in `winui-svelte/enums`
+
+### Audit (`winui-svelte/accessibility/audit`)
+
+`auditAccessibility(root)` walks the visual tree of a laid-out window and returns
+typed findings; call it from `onloaded` or a button in development, and never
+import the entry in a production build
+
+```ts
+import { auditAccessibility } from "winui-svelte/accessibility/audit";
+
+for (const finding of auditAccessibility(content)) {
+  console.warn(`${finding.path}: ${finding.message} - ${finding.suggestion}`);
+}
+```
+
+| Rule id | Applies to | Finds |
+|---|---|---|
+| `unnamed-button` | buttons | no accessible name (an icon-only button with no `automationName`) |
+| `unlabeled-input` | text boxes, combo boxes, sliders, check boxes | no name, header or `automationLabeledBy` |
+| `duplicate-access-key` | interactive controls | the same `accessKey` on two elements |
+| `zero-size-focusable` | interactive controls | takes focus but has no width or height |
+| `unreachable-by-keyboard` | interactive controls | not a tab stop and no access key or keyboard accelerator |
+| `low-contrast-text` | text, buttons, inputs | below WCAG AA (4.5 to 1, 3 to 1 for large text) on a solid background the tree can resolve |
+
+- The name is what UI Automation computes (`AutomationPeer.GetName`), so it
+  counts `automationName`, a button's text, a header and a label alike
+- Contrast is measured only where the foreground is a solid brush and a solid
+  background lies behind the text (a translucent one is mixed with it);
+  gradients, acrylic and images are left alone
+- The rules are one table, `accessibilityRules`; `ruleDescriptions()` is the
+  table without its predicates, and `winui-svelte/accessibility/rules.json`
+  is the same as JSON for an editor (`pnpm gen:accessibility-rules`, checked by
+  `pnpm gen:accessibility-rules:check` in the lint gate)
+- `auditTree({ root, host })` runs the rules over any tree a host describes,
+  which is how the unit tests run them without WinUI
+- `examples/accessibility` holds a failing and a fixed form;
+  `test/accessibility.test.ts` audits it in a real window and hears
+  `announce` through a UI Automation event handler, and the gallery page
+  "Live regions and the audit" shows both
+
 ## Forms (`winui-svelte/forms`)
 
 Opt-in: nothing in the core imports it, so an app that does not use it does
@@ -3750,7 +4817,7 @@ Each area is an opt-in subpath, so an app that imports none of them bundles none
 | `winui-svelte/devices/input` | `inputDevices`, `readInputCapabilities` |
 | `winui-svelte/devices/bluetooth` | adapter, devices, `bluetoothScanner`, `scanBluetoothAdvertisements`, GATT, UUIDs, radios |
 | `winui-svelte/devices/printers` | `printers`, `listPrinters`, `printFile` |
-| `winui-svelte/devices/power` | `battery` |
+| `winui-svelte/devices/power` | `battery`, `systemPower` |
 | `winui-svelte/devices/network` | `networkInformation` |
 | `winui-svelte/devices/audio` | `audioDevices` |
 | `winui-svelte/devices/display` | `displays`, `getDisplayMonitors` |
@@ -3771,7 +4838,7 @@ Everything here was checked to work from `node.exe` with no package identity;
 - A list is a keyed reactive collection (`KeyedCollection`): `{#each collection.items as device (device.id)}`, with `get(key)`, `has(key)`, `keys` and `size`
 - A change makes a new snapshot object, so a keyed block redraws the row
 - Every rune reads through a `source` (or `defaults`, `list`, `createSource`) option whose default is the Windows end: `windowsInputSource`, `windowsPowerSource`, `windowsNetworkSource`, `windowsAudioDefaults`, `windowsDisplaySource`, `windowsGamepadSource` and `windowsPrinterSource` are those defaults, exported so a test or a wrapper can use or replace them
-- The WinRT enums the results are made of are re-exported under their own names: `AudioDeviceRole`, `BatteryStatus`, `BluetoothCacheMode`, `BluetoothLEScanningMode`, `DisplayMonitorConnectionKind`, `EnergySaverStatus`, `GamepadButtons`, `NetworkConnectivityLevel`, `NetworkCostType`, `PointerDeviceType`, `PowerSupplyStatus`, `RadioAccessStatus`, `RadioKind`, `RadioState`
+- The WinRT enums the results are made of are re-exported under their own names: `AudioDeviceRole`, `BatteryStatus`, `BluetoothCacheMode`, `BluetoothLEScanningMode`, `DisplayMonitorConnectionKind`, `DisplayStatus`, `EffectivePowerMode`, `EnergySaverStatus`, `GamepadButtons`, `NetworkConnectivityLevel`, `NetworkCostType`, `PointerDeviceType`, `PowerSupplyStatus`, `RadioAccessStatus`, `RadioKind`, `RadioState`, `UserPresenceStatus`
 
 ### Device enumeration
 
@@ -3914,6 +4981,7 @@ build; print the document to a file and use `printFile`, or draw it with Win2D
 | Rune | Reads | Fields |
 |---|---|---|
 | `battery()` | `Battery.AggregateBattery`, `PowerManager` | `hasBattery`, `percent`, `isCharging`, `isDischarging`, `isOnAcPower`, `isEnergySaverOn`, `remainingDischargeMilliseconds`, `healthPercent`, `reading` |
+| `systemPower()` | `Microsoft.Windows.System.Power.PowerManager` (Windows App SDK) | `displayStatus`, `isDisplayOn`, `effectivePowerMode`, `isUserPresent`, `resumeCount`, `reading` |
 | `networkInformation()` | `NetworkInformation` | `isOnline`, `connectivity`, `profileName`, `isMetered`, `isRoaming`, `isWifi`, `isMobile`, `signalBars`, `reading` (with every profile name) |
 | `displays()` | `DisplayArea` and its watcher | `areas` (bounds and work area), `primary`, `count`; needs the Windows App SDK, which a window has |
 | `getDisplayMonitors()` | `DisplayMonitor` | name, native resolution, physical size, DPI, luminance; needs no window |
@@ -3927,6 +4995,14 @@ build; print the document to a file and use `printFile`, or draw it with Win2D
 - A GATT call that does not succeed throws `BluetoothLowEnergyError` with the `GattCommunicationStatus` (`Unreachable`, `ProtocolError`, `AccessDenied`)
 - `getBluetoothAdapter()` resolves to `null` and `radios` is empty when the machine has no adapter
 - An event Windows refuses to an app without a package identity is left unsubscribed: the value is still read live, it only does not update by itself
+- `systemPower` polls once a second and does not subscribe to `PowerManager`'s
+  events: any subscription (even one removed again) keeps the Node process from
+  exiting, and Windows raises them on a thread of its own, which dynwinrt does
+  not deliver; `SystemSuspendStatus` cannot be read before its event has fired,
+  so `resumeCount` counts a wake as a gap of over ten seconds between two
+  ticks; `userPresenceStatus` reads 2 until Windows has said (a value the
+  bindings do not name); `EnergySaverStatus` is the one `battery` already
+  reads (`isEnergySaverOn`); the properties need the Windows App SDK
 - A machine without a sensor, gamepad, battery or printer reports it (`isAvailable` false, an empty list, `hasBattery` false), never an error
 - The radio state, pairing prompts, Bluetooth consent and the microphone are the user's: reading a list needs no consent, using a device can
 
@@ -3949,6 +5025,58 @@ Does not work or is not offered:
 - Gamepad input while the window is in the background: Windows delivers it to the focused window
 - Sensors on a desktop: there are none, so `isAvailable` is false
 
+## Store and package (`winui-svelte/store`)
+
+The Microsoft Store and package APIs (`Windows.Services.Store.StoreContext`,
+`Windows.ApplicationModel.Package`, `PackageCatalog`, `StartupTask`) as typed
+async calls and events, opt-in
+Every call that needs a package identity answers `{ hasPackage: false }` outside
+a package (plain Node.js, Electron, `pnpm dev`) and never throws for the missing
+identity; inside one it answers `{ hasPackage: true, value }`
+The check is `GetCurrentPackageFullName`, not the exception `Package.Current`
+throws
+
+| Export | What |
+|---|---|
+| `hasPackage()`, `getPackageInfo()` | whether the process has an identity; the package's name, full name, family name, publisher, version and install path, or null |
+| `getAppLicense({ window })` | `isActive`, `isTrial`, `skuStoreId`, `expirationDate` (null when it never ends) |
+| `watchLicense({ window, pollMilliseconds })` | a `LicenseWatcher` that raises `offlinelicenseschanged` (`onofflinelicenseschanged`); `close()` stops it |
+| `checkForUpdates({ window })` | `{ updates, hasMandatory, install({ onprogress }) }`: nothing is downloaded until `install` is called, and it installs exactly the updates found |
+| `watchPackages()` | a `PackageWatcher` that raises `packagestaging`, `packageinstalling` and `packageupdating` (`PackageProgressEvent`, with `progress`, `isComplete`, `errorCode`) |
+| `getStartupTask({ taskId })` | the task's `state`, `enable()` (a request: read the state it returns) and `disable()` |
+| `UpdateState`, `StartupState`, `PackageStage` | the closed sets, each a value plus a type |
+| `windowsStoreBackend` | the real backend over the WinRT classes; `StoreBackend` is the interface the calls take, so a test swaps it |
+
+`window` is the owner of any Store dialog: a `WindowHandle` or the native
+`Window`; it is given to `IInitializeWithWindow` on the `StoreContext`, as a
+desktop app must
+Without it a call that shows UI is refused by Windows
+
+Events and threads: dynwinrt delivers a callback only when Windows raises it on
+the UI thread
+`OfflineLicensesChanged` and the `PackageCatalog` events come from a thread of
+their own, so they may never arrive
+`watchLicense` takes `pollMilliseconds` to read the licence on a UI-thread timer
+and raise the same event when it changed (as `winui-svelte/media` polls the
+player); `install`'s `onprogress` is an async progress callback and does arrive
+Treat `watchPackages` as a hint, not a guarantee
+
+What was checked from `node.exe` with no package identity: `hasPackage()` is
+false, `getPackageInfo()` is null, and every other call answers
+`hasPackage: false` (`src/store/store.test.ts`; it installs and downloads
+nothing)
+What cannot work without an identity: the licence, the Store update check and
+install, the package events and startup tasks all, because Windows ties them to
+the package
+Under MSIX they are expected to work as documented, but nothing here has run
+under a real package yet
+
+Replaces in the any-stt panel: with `getAppLicense`, `watchLicense`,
+`checkForUpdates`, `watchPackages` and `getStartupTask` running in the packaged
+`node.exe`, the Rust launcher no longer needs `licence.rs`, `updates.rs`,
+`store.rs` or its `--startup-task` mode
+Delete them once the calls are confirmed under the package
+
 ## Reference: the remaining exports
 
 Exports that other sections do not need to name; each has JSDoc in its source
@@ -3967,7 +5095,7 @@ entry point is named nowhere in the docs
 | `releaseFragment`, `rootControl`, `watchRoot`, `unwatchRoot`, `swapControl` | `winui-svelte/host` | the renderer's mount-target plumbing: release what nodes hold, find the root, watch and unwatch it, replace a control in place |
 | `classNameOf` | `winui-svelte/host` | the class name (`ListView`) of a control, from the tag it was registered under, so it holds when a minifier renames classes |
 | `createCssNative`, `installCssRuntime`, `unregisterStyleSheet`, `textTransforms` | `winui-svelte/css` | the CSS runtime's WinUI boundary, its installer, removal of a stylesheet, and the text each element's `text-transform` shows (the renderer reads it) |
-| `animationGroups`, `effectGroups`, `visualEffectGroups`, `clipGroups`, `cursorGroups`, `environmentGroups`, `gradientGroups`, `containerGroups`, `compatGroups`, `focusGroups`, `positionGroups`, `queryGroups`, `resourceGroups`, `surfaceGroups`, `transformGroups` | `winui-svelte/css/*` | the property groups each opt-in subpath adds |
+| `animationGroups`, `effectGroups`, `visualEffectGroups`, `clipGroups`, `cursorGroups`, `environmentGroups`, `gradientGroups`, `containerGroups`, `compatGroups`, `focusGroups`, `positionGroups`, `queryGroups`, `resourceGroups`, `scrollTimelineGroups`, `surfaceGroups`, `transformGroups`, `viewTransitionGroups`, `visualStateGroups` | `winui-svelte/css/*` | the property groups each opt-in subpath adds |
 | `SHEET_SUFFIX`, `SheetError` | `winui-svelte/css/sheet-module` | the module-name suffix of a compiled stylesheet; a stylesheet WinUI cannot say |
 | `translateComponent` | `winui-svelte/css/sheet-module` | the build's translation of a component's `<style>`, which the validator and the Vite plugin share |
 | `unusedSelectorMessages` | `winui-svelte/css/sheet-module` | the messages of Svelte's unused-selector warnings for a component read with its instances as elements, which `winuiWarningFilter` keeps |
@@ -4001,6 +5129,12 @@ event announces, such as an unreferenced timer) and uses next to no CPU
 The one thing nobody can ask libuv from outside is when its next timer fires:
 while Node itself holds a timer (a socket timeout) the pump wakes every 16 ms
 The timers an app makes go through the scheduler, which the dispatcher drives
+Measured idle cost, over 20 seconds after a minute of settling, on Windows 11
+(build 26300) with a 32-thread CPU and the Windows App SDK 2.2 build of this
+repository: `examples/hello` used 0.15 percent of one core and `examples/tray`
+(a tray icon and no window) used 0.23 percent, so nothing in the idle path needs
+fixing; the first seconds after start cost more (about 2 percent of a core) while
+the window loads
 A host that calls `process.exit` while the window runs would end the process
 under WinUI's thread (a delegate then finds the Node environment closing, and
 the process can end with 0xC000027B); `initWindowsAppSdk` therefore installs