@vestra-player/sdk 1.5.29 → 1.5.30

package/llms-full.txt

@@ -1,8 +1,8 @@
-# @vestra-player/sdk 1.5.29: full reference
+# @vestra-player/sdk 1.5.30: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
-How to read this file: the declarations are TypeScript declaration files whose doc comments keep only the description and the tags @capability (the manifest capability a call needs), @player (the oldest player version), @param, @returns, @throws (`code` (throws | rejects) condition) and @deprecated. Examples and longer remarks are in the documentation site and in node_modules/@vestra-player/sdk/dist/**/*.d.ts. Only what is declared here exists; do not use other members.
+How to read this file: the declarations are TypeScript declaration files whose doc comments keep the description, @remarks, the tags @capability (the manifest capability a call needs), @player (the oldest player version), @param, @returns, @throws (`code` (throws | rejects) condition) and @deprecated, and every @example (a task title, a lead saying what it does and how it works, then code). @see, @since and the rest are on the documentation site and in node_modules/@vestra-player/sdk/dist/**/*.d.ts. Only what is declared here exists; do not use other members.
 
 Limits: 160 commands per plugin and 1024 in the player (`limit`); menu ids for the first path segment: `@open`, `@playback`, `@subtitles`, `@video`, `@audio`, `@screen`, `@settings`; manifest: id ≤ 128 bytes, name, author ≤ 64 characters, punchline ≤ 120, description ≤ 2000, tags ≤ 8 of ≤ 24 characters, license ≤ 64, sourceUrl ≤ 2048 bytes, icon PNG or JPEG ≤ 512 KB and 1024 px per side, readme, changelog ≤ 256 KB.
 
@@ -3304,6 +3304,18 @@ interface Disposable {
 }
 ```
 
+Example: Stop listening once the file is ready
+
+The listener reacts to the first time the source becomes ready and then
+stops being called. Every registration returns a `Disposable`;
+disposing it removes just that listener, before the scope that owns it
+ends.
+```ts
+const subscription = plugin.player.onChange((state) => {
+  if (state.phase === "ready") void subscription.dispose();
+});
+```
+
 ### PluginError
 
 Every API failure is an ordinary `Error` with a stable string `code`.
@@ -3365,6 +3377,21 @@ type PluginError = Error & {
 };
 ```
 
+Example: Ignore a seek that lost a race, rethrow anything else
+
+The plugin seeks to 0:30 and stays quiet when another file was opened in
+between. Every failure is an `Error` with a stable `code`; `stale` means
+the source changed since the state the call was based on and nothing
+was done, so it is safe to drop. Other codes are real failures.
+```ts
+try {
+  await plugin.player.seek(30);
+} catch (error) {
+  if ((error as PluginError).code === "stale") return; // someone else changed the source
+  throw error;
+}
+```
+
 ### Scope
 
 A group of handles released together.
@@ -3472,6 +3499,14 @@ interface Scope extends Disposable {
   /**
    * Run `cleanup` when this scope is disposed (for example `clearInterval` or closing a socket). It may be async; errors are logged.
    * @returns A handle that cancels the registration early (without running `cleanup`).
+   * @example Stop a timer when the plugin stops
+   * A once-a-second refresh runs as long as the plugin does. `onDispose`
+   * runs the cleanup when the scope is disposed, which for `plugin` is
+   * when the player stops the plugin, so the timer never outlives it.
+   * ```ts
+   * const timer = setInterval(() => plugin.update(), 1000); // re-evaluate bindings
+   * plugin.onDispose(() => clearInterval(timer));
+   * ```
    */
   onDispose(cleanup: () => void | Promise<void>): Disposable;
   /**
@@ -3482,6 +3517,16 @@ interface Scope extends Disposable {
    * Rejections of async handlers count too, and so do failures of
    * registrations made after activation (a command whose `ready` rejects,
    * a property write the player refused).
+   * @example Show errors from handlers on the OSD
+   * When a menu command, a window callback or a listener of the plugin
+   * fails, the user sees why. The SDK catches what those handlers throw
+   * (and their rejected promises) and passes it here instead of only
+   * logging it; the message is data in a translated template.
+   * ```ts
+   * plugin.onError((error) => {
+   *   void plugin.osd.show("Bookmarks: {}", [error.message]);
+   * });
+   * ```
    */
   onError(listener: (error: PluginError) => void): Disposable;
   /**
@@ -3496,6 +3541,30 @@ interface Scope extends Disposable {
 }
 ```
 
+Example: Rebuild a dynamic submenu with a child scope
+
+Subtitles ▸ Track lists the current file's subtitle tracks and is
+rebuilt whenever they change. Commands added through a child scope
+belong to it; disposing the scope removes all of them at once, and a
+new child scope collects the next set.
+```ts
+let tracks = plugin.scope();
+plugin.subtitles.onChange(async (state) => {
+  await tracks.dispose(); // removes the previous menu items
+  tracks = plugin.scope();
+  state.tracks.forEach((track, i) =>
+    tracks.commands.add({
+      id: `track.${i}`,
+      path: ["Subtitles", "Track", track.title],
+      order: 300 + i,
+      radio: true,
+      checked: () => plugin.subtitles.state?.selected?.id === track.id,
+      run: () => plugin.subtitles.select(track),
+    }),
+  );
+});
+```
+
 ### Plugin
 
 The object the player passes to a plugin's `activate`: the root
@@ -3538,6 +3607,25 @@ interface Plugin extends Scope {
 }
 ```
 
+Example: Write a minimal plugin with one menu item
+
+Tools ▸ Say hello, or Ctrl+H, shows "Hello from" and the plugin's id.
+The player imports `main.ts`, calls its default export with the
+`Plugin` object, and keeps the registrations made during activation;
+the manifest declares the capabilities `commands` and `ui.osd`.
+```ts
+import type { Plugin } from "@vestra-player/sdk";
+
+export default async function activate(plugin: Plugin) {
+  plugin.commands.add({
+    id: "hello",
+    path: ["Tools", "Say hello"],
+    bindings: ["Ctrl+H"], // a default the user can change
+    run: () => plugin.osd.show("Hello from {}", [plugin.id]),
+  });
+}
+```
+
 ### CommandState
 
 The state of a command's menu item, as the player shows it.
@@ -3564,6 +3652,22 @@ Scope.update); only changes are sent to the player.
 type Bindable<T> = T | (() => T);
 ```
 
+Example: Mix a computed state with a fixed one
+
+The Loop item carries a check mark while a loop is set and is always
+enabled. A function is evaluated again in every update pass (after each
+handler and player state change) and only changes are sent; a plain
+value never changes.
+```ts
+plugin.commands.add({
+  id: "loop",
+  path: ["Playback", "Loop"],
+  checked: () => plugin.player.state.loop != null, // re-evaluated
+  enabled: true, // a fixed value
+  run: () => plugin.player.setLoop(null),
+});
+```
+
 ### MenuId
 
 A built-in top-level menu of the player, named in a command path as
@@ -3589,6 +3693,32 @@ type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "open" | "
 
 A command's button on the bottom bar: CommandOptions.button.
 
+**Where it shows.** The bottom bar places the player's strip of command
+buttons, `BarButtons` from `@vestra/bar-buttons.slint`, at its right end;
+the player fills it with the buttons of every plugin, left to right by
+`order`, and its own sidebar toggle rightmost. When the window is narrow
+the strip loses cells from its outer (left) end inward: the lowest order
+goes first, the sidebar toggle last. A
+bottom bar that does not place `BarButtons` shows no buttons: the
+command's menu entry stays, and the player logs the buttons it cannot
+show and whose bar hides them. The built-in bar (`vestra.playback`) places
+it; see
+Writing a bottom bar.
+
+**What it shows.** The icon, the command's title (translated, a trailing
+"…" removed) and its first key as the tooltip ("Plugin Store (F9)"),
+`enabled`, `busy` and `reason` as the menu item has them: a disabled or
+busy command's button is drawn disabled, its tooltip adds the reason, and
+a click runs nothing. A command with `checked` shows its icon in the
+accent colour while checked. A click runs the command exactly like a
+click on its menu item.
+
+**Limits.** One button per plugin and eight in the player
+(`BAR_BUTTON_LIMITS`): a button past them is left out (its command and
+menu entry stay) and the player logs it with `limit`. The button goes
+with its command: disposing the command, or disabling, stopping or
+uninstalling the plugin, removes it.
+
 - @player 0.5.10; older players show the menu entry without a button (declare `"minPlayerVersion": "0.5.10"` when the button matters).
 
 ```ts
@@ -3604,6 +3734,23 @@ interface CommandButton {
 }
 ```
 
+Example: Give a command a button in the bottom bar
+
+A Store icon appears in the bottom bar's button strip; a click opens
+the store window, exactly like the menu item. The player draws the
+button from the command's title, keys and state, and places it by
+`order` (200 is where the player's own Plugin Store button sits); a
+bar that does not place `BarButtons` shows only the menu item.
+```ts
+const store = plugin.windows.create("ui/store.slint");
+plugin.commands.add({
+  id: "open",
+  path: ["Plugin Store…"], // a button needs a menu path
+  button: { icon: "store", order: 200 },
+  run: () => store.show(),
+});
+```
+
 ### CommandOptions
 
 The declaration passed to Commands.add.
@@ -3663,6 +3810,22 @@ interface CommandOptions {
    * Text (SDK 1.5.11, player 0.4.3): `plugin.i18n.text("Track {}
    * ({})", [n, codec])`. The menu shows it translated and filled in; it
    * merges by its English rendering ("Track 2 (opus)").
+   * @example Put items into built-in menus, one with a track number
+   * "Blur" appears in the Video menu and "Track 2 (opus)" under Audio ▸
+   * Audio Track, both in the user's language. `@video` and `@audio` name
+   * the built-in menus by id; "Audio Track" is a submenu key that merges
+   * with any other plugin's same key; the `text()` segment is translated
+   * with the plugin's catalog and then filled in with the number and codec.
+   * ```ts
+   * plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run: toggle });
+   * const { text } = plugin.i18n;
+   * // A segment with data: translated as "Track {} ({})", then filled in.
+   * plugin.commands.add({
+   *   id: "track-2",
+   *   path: ["@audio", "Audio Track", text("Track {} ({})", [2, "opus"])],
+   *   run: select,
+   * });
+   * ```
    */
   path?: (string | Text)[];
   /** Menu label (English source text, shown translated, or a Text); defaults to the last path segment. */
@@ -3730,7 +3893,28 @@ from the menu and the binding table; the id can be added again right away.
 interface Command extends Disposable {
   /** The local id given in CommandOptions.id. */
   readonly id: string;
-  /** Replace some state fields (values or functions). Last write wins. */
+  /**
+   * Replace some state fields (values or functions). Last write wins.
+   * @example Show a command as busy while it works
+   * The Export item shows as busy with "Exporting…" as its reason while the
+   * export runs, then returns to normal. `set` replaces only the fields it
+   * names and the SDK sends the new state to the player; a busy command's
+   * menu item and key do not run it again until it is set back.
+   * ```ts
+   * const exportCommand = plugin.commands.add({
+   *   id: "export",
+   *   path: ["@video", "Export…"],
+   *   run: async () => {
+   *     exportCommand.set({ busy: true, reason: "Exporting…" });
+   *     try {
+   *       await runExport();
+   *     } finally {
+   *       exportCommand.set({ busy: false, reason: null }); // also on failure
+   *     }
+   *   },
+   * });
+   * ```
+   */
   set(state: Partial<{
     [K in keyof CommandState]: Bindable<CommandState[K]>;
   }>): void;
@@ -3754,6 +3938,23 @@ interface Commands {
    * Titles and paths cannot change in place: put changing items (track
    * lists, presets) in a child Scope and rebuild it.
    * @throws invalid synchronously for a malformed path (including an unknown `@` menu id), order, group or binding; `conflict` for an id this plugin has already declared and not disposed.
+   * @example Pause playback from a menu item
+   * Playback ▸ Pause (and Ctrl+P) pauses and resumes, shows a check mark
+   * while paused and is greyed out when nothing can be paused. The player
+   * calls `run` when the user picks the item or presses its key; `enabled`
+   * and `checked` are functions the SDK evaluates again after every
+   * handler and player state change, sending only what changed.
+   * ```ts
+   * const toggle = plugin.commands.add({
+   *   id: "toggle-pause",
+   *   path: ["Playback", "Pause"],
+   *   order: 210, // position among the Playback menu's items
+   *   bindings: ["Ctrl+P"],
+   *   enabled: () => plugin.player.state.can.pause,
+   *   checked: () => plugin.player.state.paused,
+   *   run: () => plugin.player.setPaused(!plugin.player.state.paused),
+   * });
+   * ```
    */
   add(options: CommandOptions): Command;
 }
@@ -3763,6 +3964,18 @@ interface Commands {
 
 An image file for a Slint `image` property, made by Ui.image.
 
+Opaque: pass it where the Slint type is `image`, with View.set or
+View.bind: the whole value of an `image` property or, from SDK
+1.5.19 (player 0.5.1), an `image` field at any depth, such as the logo of
+each row of a list. Making the reference does not read the file: the
+player checks and decodes it each time it receives the value (a property
+write, a window opening; Ui.image has the rules and limits).
+
+A reference belongs to the Scope that created it. Once that scope
+is disposed, writing the reference fails with `invalid` (reported to
+Scope.onError); an image already on screen stays until the
+property changes or the view closes.
+
 ```ts
 interface ImageRef {
   /** The path given to Ui.image, unchanged. */
@@ -3772,6 +3985,43 @@ interface ImageRef {
 }
 ```
 
+Example: Show a cover image from the data directory
+
+A window opens showing `cover.png`, which the plugin saved in its data
+directory. `ui.image` only makes a reference, without reading the file;
+the player checks and decodes the file when it receives the value, so a
+missing file fails that write with `missing` (here: `show` rejects, as
+it is an initial property). A missing image nested inside a value is
+drawn empty instead.
+```ts
+const cover = plugin.windows.create("ui/cover.slint");
+// `art` is an `image` property in ui/cover.slint.
+cover.set({ art: plugin.ui.image(`${plugin.dataDirectory}/cover.png`) });
+await cover.show();
+```
+
+Example: Show a logo in each row of a list
+
+Each row of the list draws its own small logo next to its name. An
+`ImageRef` may sit in any field of a property value (SDK 1.5.19, player
+0.5.1), so the rows carry their icons; `maxSide: 64` decodes each logo
+at most 64 px wide, which keeps the view's image memory small.
+```slint
+export struct Row { key: string, name: string, icon: image }
+```
+```ts
+const items = [{ id: "a", name: "A", iconPath: `${plugin.dataDirectory}/a.png` }];
+const list = plugin.windows.create("ui/list.slint");
+list.bind(() => ({
+  rows: items.map((item) => ({
+    key: item.id,
+    name: item.name,
+    // About twice the drawn size (32 px) stays sharp on dense screens.
+    icon: plugin.ui.image(item.iconPath, { maxSide: 64 }),
+  })),
+}));
+```
+
 ### ImageOptions
 
 Options of Ui.image and Ui.remoteImage.
@@ -3791,6 +4041,18 @@ interface ImageOptions {
 A Markdown document for `MarkdownView` or `MarkdownBlocks`, made by
 Ui.markdown.
 
+Opaque, like ImageRef: pass it where the Slint type is
+`[MarkdownBlock]`: the whole value of such a property (the `blocks` of
+`MarkdownView` from `@vestra/markdown.slint`) or, from SDK 1.5.4, a
+`[MarkdownBlock]` field at any depth of a property value, such as the
+`body` of each row of a chat's message list. It carries the text, the
+base address and the local copies of its remote images; the player parses
+and draws it. Writing a document whose text did not change (a new
+reference for the same text included) costs the player no parsing, and a
+changed document updates only the blocks that changed. It belongs to the
+scope that created it: once that scope is disposed, writing it fails with
+`invalid`, wherever it is in the value.
+
 - @player 0.2.0; nested in a value: the player after 0.4.0
 
 ```ts
@@ -3802,6 +4064,18 @@ interface MarkdownRef {
 }
 ```
 
+Example: Show chat messages, one document per row
+
+The chat window shows a formatted assistant message. `ui.markdown`
+resolves once the document is ready (here without downloading images);
+the reference goes into the `body` field of a row, whose Slint type is
+`[MarkdownBlock]`, and the player parses and draws it.
+```ts
+const chat = plugin.windows.create("ui/chat.slint");
+const body = await plugin.ui.markdown("**Hello**", { remoteImages: false });
+chat.set({ messages: [{ id: "m1", role: "assistant", body }] });
+```
+
 ### MarkdownOptions
 
 Options of Ui.markdown: where relative links and images point, and
@@ -3823,6 +4097,46 @@ interface MarkdownOptions {
 The value of one Slint property: JSON with Markdown documents and images
 at any depth (PropData).
 
+JSON becomes Slint values as you would expect: booleans for `bool`,
+finite numbers for `int` and `float`, strings for `string`, arrays for
+models (`[T]`), objects for structs. Struct field names are passed
+unchanged, so write them as the Slint file spells them; a name with `_`
+is refused (Slint treats `_` and `-` as the same, so use camelCase or
+kebab-case).
+
+A Text or TextList goes where the Slint type is `string`,
+at any depth (SDK 1.5.11, player 0.4.3): the player shows it translated
+with the plugin's catalog, so a `[string]` model (a ComboBox) can mix
+words and data. The limits below count it as the string it becomes.
+
+A MarkdownRef goes where the Slint type is `[MarkdownBlock]`: the
+whole value, or a field at any depth (SDK 1.5.4; older players refuse a
+nested one). An ImageRef goes where the Slint type is `image`: the
+whole value, or a field at any depth (SDK 1.5.19, player 0.5.1; older
+players refuse a nested one with `invalid`). The images nested in the
+values of one view (a window, panel or settings page) may show at most
+32 MB of decoded pixels together (`IMAGE_LIMITS.viewBytes` in
+`@vestra-player/sdk/runtime`): a write
+that would pass it is refused with `limit`; use
+ImageOptions.maxSide for small pictures such as logos and
+thumbnails.
+
+Limits per value (`UI_VALUE_LIMITS` in `@vestra-player/sdk/testing`,
+player 0.4.3; older players: 4096 values and 1024 rows): nesting depth 8,
+16384 values in total (every array, object, string, number, boolean and
+null counts, the value itself included; a document or an image is one), 4096 rows
+per array, 64 KiB per string or field name and 1 MiB of text in total,
+field names and the text of its Markdown documents included (256 KB per
+document). A list of rows with 8 fields is 9 values per row, so about
+1800 rows fit. The whole request must also fit the player's 1 MiB
+message. A value over a limit is refused with code `limit` and the
+property keeps what it showed (see View.set); `TestHost` refuses
+it the same way.
+
+The limits bound the work of one write, not the size of your data: for
+a list that can grow without bound, send the rows near the view and the
+row count, and move that window as the user scrolls.
+
 ```ts
 type PropValue = PropData | ImageRef;
 ```
@@ -3838,34 +4152,108 @@ type PropData = null | boolean | number | string | MarkdownRef | ImageRef | Text
 };
 ```
 
+Example: Type a message list whose rows carry a document
+
+A property value for a chat's message list, typed so that TypeScript
+accepts a Markdown document inside each row. `PropData` is the JSON a
+property takes plus documents and images at any depth; the player turns
+each object into a Slint struct by its field names.
+```ts
+const messages: PropData = [
+  { id: "m1", role: "user", body: await plugin.ui.markdown("Hi") },
+];
+```
+
 ### Props
 
 Properties to write to a view, by name.
 
+Names may be camelCase: the SDK turns every capital letter into `-` plus
+the lower-case letter (`canMark` → `can-mark`); names already in
+kebab-case are kept. Only the property names are converted, not the
+fields of struct values.
+
 ```ts
 type Props = Record<string, PropValue>;
 ```
 
+Example: Prepare a window's initial properties
+
+An object of property values by name, as `windows.create` and
+`View.set` take them. Names match the Slint file (`canMark` for
+`can-mark`), and each value becomes the Slint type of its property: a
+boolean, and an array of structs for a model.
+```ts
+const props: Props = { canMark: true, rows: [{ rowId: "a", title: "First" }] };
+```
+
 ### Ui
 
 Values for Slint properties that are not plain JSON: images from files and
 Markdown documents. `plugin.ui`.
 
+A Slint file can only name images compiled into it (`@image-url`). To show
+an image the plugin picks at run time (cover art, a thumbnail it rendered,
+a downloaded icon), make an ImageRef with Ui.image and
+write it to an `image` property. To show formatted text, make a
+MarkdownRef with Ui.markdown and give it to `MarkdownView`.
+Both work in tool windows, panels (the backdrop and the floating sidebar
+included) and settings pages.
+
 - @capability None.
 
 ```ts
 interface Ui {
   /**
    * Reference a PNG or JPEG file for an `image` property.
+   *
+   * Returns at once without touching the file. The player checks the file
+   * each time it receives the reference (a property write, a window or
+   * settings page opening, the main window being rebuilt): it must be inside this plugin's package
+   * directory or Plugin.dataDirectory after following links, at most
+   * 16 MB and 4096×4096 pixels, and PNG or JPEG by content (the extension
+   * does not matter). A failed check of a whole-value image is a failed
+   * property write: `missing` for a file that does not exist, `invalid`
+   * otherwise. It goes to Scope.onError and the property keeps its
+   * previous image; in the initial properties of a tool window it makes
+   * Window.show reject. A nested image (a field of a row, SDK
+   * 1.5.19) that fails its check is drawn empty instead, and the rest of
+   * the value is shown, as a Markdown image shows its alt text.
+   *
+   * The player caches decoded images per plugin (up to 64 MB, least recently
+   * used first) by path, size and modification time, and does not watch
+   * files. After rewriting a file under the same path, call `image()` again
+   * and write the new reference: the SDK does not send a value that did not
+   * change, so the player would not look at the file again.
    * @capability None.
    * @param path - Absolute path of the image file, inside the package directory or the data directory.
    * @param options - `maxSide` (SDK 1.5.19, player 0.5.1): decode the image scaled down, aspect kept, so that neither side is over it.
    * @returns A new ImageRef, owned by this scope.
    * @throws invalid (throws) `path` is not a non-empty string, or `maxSide` is not an integer 1–4096.
+   * @example Show a thumbnail the plugin rendered
+   * A window shows a PNG the plugin wrote into its data directory. The file
+   * must be inside the package or data directory; `image` returns at once.
+   * The player decodes the file when it receives the value and notices a
+   * rewritten file by its size and modification time; the plugin still
+   * calls `image()` again after rewriting it, because the SDK does not send
+   * a value that did not change.
+   * ```ts
+   * const window = plugin.windows.create("ui/thumbnail.slint");
+   * const file = `${plugin.dataDirectory}/thumbnail.png`;
+   * // … write the PNG to `file` (for example with plugin.tools.run("ffmpeg", …)) …
+   * window.set({ thumbnail: plugin.ui.image(file) });
+   * await window.show();
+   * ```
    */
   image(path: string, options?: ImageOptions): ImageRef;
   /**
    * Download an `https:` PNG or JPEG image (a thumbnail, a repository's plugin icon) and reference the local copy, as Ui.image does.
+   *
+   * Downloads like Ui.markdown's remote images: Node's `fetch` in
+   * this plugin's process, at most 4 MB and 10 s per image, 4 downloads at a
+   * time per plugin, into `<dataDirectory>/.vestra-cache/images/`; the cache
+   * keeps 32 MB and fetches an address again after 24 hours, so a list that
+   * shows the same thumbnails again reads them from disk.
    * @capability None (the plugin process has network access).
    * @player Any (the reference is an ordinary ImageRef); nested in a value, player 0.5.1.
    * @param url - The image's `https:` address.
@@ -3873,10 +4261,55 @@ interface Ui {
    * @returns The reference, owned by this scope, once the file is in the cache.
    * @throws invalid (rejects) `url` is not an `https:` address, or `maxSide` is not an integer 1–4096.
    * @throws unavailable (rejects) the download failed, timed out, was too large, or is not a PNG or JPEG image; or the plugin has no data directory.
+   * @example Show search results with downloaded thumbnails
+   * A results window lists each hit with its thumbnail, or a placeholder
+   * when a thumbnail cannot be fetched. `remoteImage` downloads the image
+   * in the plugin's process into the data directory's cache (at most 4 at a
+   * time) and resolves with a local reference; a failed download rejects
+   * with `unavailable`, which the `catch` turns into the placeholder.
+   * ```ts
+   * const results = [{ title: "A", thumbnailUrl: "https://example.com/a.jpg" }];
+   * const placeholder = plugin.ui.image(`${plugin.dataDirectory}/blank.png`);
+   * const rows = await Promise.all(
+   *   results.map(async (r) => ({
+   *     title: r.title,
+   *     thumb: await plugin.ui
+   *       .remoteImage(r.thumbnailUrl, { maxSide: 320 })
+   *       .catch(() => placeholder), // `unavailable`: download failed
+   *   })),
+   * );
+   * plugin.windows.create("ui/results.slint").set({ rows });
+   * ```
    */
   remoteImage(url: string, options?: ImageOptions): Promise<ImageRef>;
   /**
    * Prepare a Markdown document for `MarkdownView` (`@vestra/markdown.slint`).
+   *
+   * The player renders headings, paragraphs (bold, italic, strikethrough,
+   * inline code, links), lists and task lists, code blocks, block quotes,
+   * images, tables and rules; embedded HTML is not shown. A click on a link
+   * calls the view's `link-clicked(url)` callback with the address resolved
+   * against `base`; opening it is up to the plugin (for example with
+   * System.openUrl).
+   *
+   * Images: PNG or JPEG. Local ones follow Ui.image's rules (this
+   * plugin's package or data directory). `https:` images are downloaded by
+   * this call into `<dataDirectory>/.vestra-cache/markdown/` (each at most
+   * 4 MB and 10 s, at most 64 per document; the cache keeps 32 MB and fetches
+   * an address again after 24 hours). A failed or unsupported image (SVG,
+   * GIF, `http:`…) shows its alt text; the call itself does not fail for it.
+   *
+   * The text is at most 256 KB; very long documents are cut off after 4000
+   * blocks.
+   *
+   * `MarkdownView` scrolls one document. `MarkdownBlocks` (SDK 1.5.4, players
+   * after 0.4.0) draws one without scrolling, as tall as its content, for a
+   * layout of your own or a `ListView` row. For a list of documents, write
+   * the whole list with one document per row: the player parses only the
+   * documents that changed and updates the list in place (rows added or
+   * removed at the end, a growing document's changed blocks), so re-sending
+   * the list on every streamed chunk keeps the scroll position and costs
+   * little.
    * @capability None.
    * @player 0.2.0 (set `"minPlayerVersion": "0.2.0"` in the manifest)
    * @param text - The Markdown source (CommonMark with GitHub tables, task lists and strikethrough), at most 256 KB as UTF-8.
@@ -3884,56 +4317,363 @@ interface Ui {
    * @returns The document, owned by this scope, once its remote images are downloaded (or have failed).
    * @throws invalid (rejects) `text` is not a string or is over 256 KB, or `base` is neither an `http(s):` address nor an absolute path.
    * @throws unsupported (rejects) The player is older than 0.2.0.
+   * @example Build a chat with one Markdown document per row
+   * A chat window lists messages as formatted text, with a Copy button on
+   * each code block that puts the code on the clipboard. Each row's `body`
+   * is a document from `ui.markdown`; the whole list is written again on
+   * each change, and the player parses only the documents that changed.
+   * `MarkdownBlocks` with `code-copy` calls `copy-code`, which the plugin
+   * handles with `on("copyCode")`.
+   *
+   * `ui/chat.slint`:
+   *
+   * ```slint
+   * import { ListView } from "std-widgets.slint";
+   * import { MarkdownBlocks, MarkdownBlock } from "@vestra/markdown.slint";
+   * export struct Message { id: string, role: string, body: [MarkdownBlock] }
+   * export component Chat inherits Window {
+   *     in property <[Message]> messages;
+   *     callback copy-code(string);
+   *     ListView {
+   *         for message in root.messages: VerticalLayout {
+   *             padding: 8px;
+   *             MarkdownBlocks {
+   *                 blocks: message.body;
+   *                 code-copy: true;
+   *                 copy-code(code) => { root.copy-code(code); }
+   *             }
+   *         }
+   *     }
+   * }
+   * ```
+   *
+   * ```ts
+   * const chat = plugin.windows.create("ui/chat.slint");
+   * const history: { id: string; role: string; text: string }[] = [];
+   * chat.on("copyCode", (code: string) => plugin.clipboard.writeText(code));
+   * // Re-send the whole list: unchanged documents cost the player nothing.
+   * async function render() {
+   *   const messages = [];
+   *   for (const { id, role, text } of history)
+   *     messages.push({ id, role, body: await plugin.ui.markdown(text) });
+   *   chat.set({ messages });
+   * }
+   * history.push({ id: "1", role: "user", text: "Show me `ls`." });
+   * await render();
+   * await chat.show();
+   * ```
+   * @example Show a README from the web
+   * A window shows a README downloaded from the web, its images included,
+   * and clicked links open in the browser. `base` makes relative links and
+   * images resolve against the README's address; `markdown` resolves after
+   * its `https:` images are downloaded. A click on a link makes
+   * `MarkdownView` call `link-clicked`, which `ui/readme.slint` forwards as
+   * `open-link`; the plugin opens the address with `openUrl`.
+   * ```ts
+   * const readmeUrl = "https://example.com/plugin/README.md";
+   * const response = await fetch(readmeUrl);
+   * if (!response.ok) throw new Error(`README: HTTP ${response.status}`);
+   * const text = await response.text();
+   * const window = plugin.windows.create("ui/readme.slint");
+   * // Bound before the first `show`, as a tool window requires.
+   * window.on("openLink", (url: string) => plugin.system.openUrl(url));
+   * window.set({ doc: await plugin.ui.markdown(text, { base: readmeUrl }) });
+   * await window.show();
+   * ```
    */
   markdown(text: string, options?: MarkdownOptions): Promise<MarkdownRef>;
 }
 ```
 
+Example: Show a Markdown file in a window (examples/markdown)
+
+A menu item opens a window with a formatted Markdown file that ships
+with the plugin. The plugin reads the file, turns it into a document
+with `ui.markdown` (relative images resolve against the plugin's
+directory through `base`) and writes it to the window's `doc` property,
+which the Slint file hands to `MarkdownView`.
+
+```ts
+// Relative links and images in sample.md resolve against this folder.
+const directory = fileURLToPath(new URL(".", import.meta.url));
+const window = plugin.windows.create("ui/document.slint");
+plugin.commands.add({
+  id: "show",
+  path: ["Examples", "Markdown example…"],
+  run: async () => {
+    const text = readFileSync(new URL("sample.md", import.meta.url), "utf8");
+    // `doc` is the window's [MarkdownBlock] property, drawn by MarkdownView.
+    window.set({ doc: await plugin.ui.markdown(text, { base: directory }) });
+    await window.show();
+  },
+});
+```
+
+`ui/document.slint`:
+
+```slint
+import { MarkdownView, MarkdownBlock } from "@vestra/markdown.slint";
+import { Theme } from "@vestra/theme.slint";
+
+export component Document inherits Window {
+    title: "Markdown example";
+    preferred-width: 520px;
+    preferred-height: 560px;
+    min-width: 280px;
+    min-height: 200px;
+    background: Theme.bg-panel;
+    in property <[MarkdownBlock]> doc;
+    MarkdownView {
+        blocks: root.doc;
+    }
+}
+```
+
 ### View
 
 The surface that tool windows, panels and settings pages share: properties
 out to Slint, callbacks in from Slint.
 
+The plugin's TypeScript and its Slint files run in different processes and
+exchange two kinds of messages. Plugin → UI: `in` and `in-out` properties,
+written with View.set or kept up to date with View.bind.
+UI → plugin: Slint callbacks (returning nothing), handled with
+View.on. A Window declares them on its exported component;
+a Panel and a SettingsPage declare them on the file's
+exported global, the bridge. The plugin cannot call Slint functions or read
+a property back: a value the user changes reaches it only through a
+callback.
+
+`bind` is the usual way: the SDK re-evaluates bound functions in every
+update pass (after each handler it calls, after player state changes, on
+Scope.update) and sends only what changed, at most one write in
+flight per view. `set` sends now, even an unchanged value.
+
+Writes that fail (a name the Slint file does not declare, a value of the
+wrong type, an image that fails its check): a bound value is not sent
+again until it changes; a `set` value is retried with back-off (0.25 s,
+doubling up to 30 s); the first failure of a series is reported to
+Scope.onError.
+
+A control whose value both the user and the plugin change needs a two-way
+binding to an `in-out` property (`value <=> root.level`). A one-way
+binding (`value: root.level`) is broken by Slint the first time the user
+moves the control.
+
 - @capability That of the view: `ui.window`, `ui.mount` or `ui.settings`.
 
 ```ts
 interface View {
   /**
    * Handle a Slint callback.
+   *
+   * The handler receives the callback's arguments as JSON (struct fields
+   * spelled as in Slint). It may be async. An error it throws, or a rejection
+   * of its promise, goes to Scope.onError. After it returns, and
+   * again when its promise settles, the SDK runs an update pass, so state it
+   * changed reaches bound properties without further calls (state changed
+   * after an `await` appears only when the promise settles; call
+   * Scope.update to show it earlier).
+   *
+   * Calling `on` again with the same name replaces the handler. A callback
+   * the plugin has no handler for is ignored.
+   *
+   * **Tool windows** forward only the callback names bound when the window
+   * opens: bind every name before the first Window.show. While the
+   * window is open, binding a new name throws; after a close the next `show`
+   * registers the names bound by then. A name the Slint file does not declare
+   * makes `show` reject. **Panels and settings pages** forward every
+   * callback of their bridge global, so bind whenever you like.
    * @capability That of the view: `ui.window`, `ui.mount` or `ui.settings`.
    * @param callback - The Slint callback's name, in camelCase (`toggleEffect`) or as written in Slint (`toggle-effect`).
    * @param handler - Receives the callback's arguments.
    * @returns A handle that removes this handler (if it is still the current one for the name).
    * @throws Error without a code (throws) On an open Window, for a name that has no handler yet.
+   * @example Keep a slider and the plugin's value in step
+   * Moving the window's brightness slider updates the plugin's value, and
+   * the slider shows it back. The Slint callback `brightness-changed`
+   * reaches the handler with the slider's value as JSON; after the handler
+   * returns, the SDK runs an update pass and `bind` sends the new value.
+   * Callbacks of a tool window must be bound before its first `show`.
+   * ```ts
+   * const picture = plugin.windows.create("ui/picture.slint");
+   * let brightness = 0;
+   * // camelCase here, `brightness-changed` in the Slint file.
+   * picture.on("brightnessChanged", (value: number) => {
+   *   brightness = value;
+   * });
+   * picture.bind(() => ({ brightness }));
+   * await picture.show();
+   * ```
    */
   on<A extends Json[]>(callback: string, handler: (...args: A) => unknown): Disposable;
   /**
    * Write properties now, even values that did not change.
+   *
+   * Each value given is sent once with the next write, even if it equals the
+   * last value sent. That makes `set` the way to pull a control back to the
+   * model value after the user moved it, or to put a one-off value (a
+   * document, an image) on screen. While the view is not open (a window
+   * before `show`, a panel before `ready`) the values are kept and become its
+   * initial properties.
+   *
+   * Do not `set` a property that a View.bind function also returns:
+   * the next update pass replaces the set value with the bound one.
+   *
+   * Never throws. A write that fails is retried with back-off and reported
+   * to Scope.onError (the first failure of a run of failures; the
+   * message names the property). A value over the limits of
+   * PropValue fails with `limit`. As an initial property (written
+   * while the view is not open) it makes Window.show reject; a
+   * panel or settings page still opens without it (the property keeps its
+   * default) and the failure goes to the plugin's `onError` (player 0.4.3;
+   * older players left it out silently).
    * @capability That of the view: `ui.window`, `ui.mount` or `ui.settings`.
    * @param props - Properties by name; see Props.
+   * @example Put a drop-down back when the user picks an entry the plugin refuses
+   * Choosing "Custom" snaps the drop-down back to the last real preset.
+   * The plugin cannot read a property back, only hear the callback; `set`
+   * sends the value even though it equals the one sent before, which is
+   * what pulls a control the user moved back to the plugin's value.
+   * ```ts
+   * const window = plugin.windows.create("ui/presets.slint");
+   * let presetIndex = 0;
+   * window.on("presetChosen", (index: number) => {
+   *   if (index > 2) window.set({ presetIndex }); // "Custom" is not a preset
+   *   else presetIndex = index;
+   * });
+   * ```
    */
   set(props: Props): void;
   /**
    * Keep properties equal to a function of the plugin's state.
+   *
+   * The SDK calls `props` in every update pass (and right after `bind`) and
+   * sends the values that differ from the ones it sent last. Because an
+   * unchanged value is not sent again, text the user typed into an `in-out`
+   * property stays until the plugin's value for it changes.
+   *
+   * Keep the function quick and synchronous: it runs often. An error it
+   * throws is reported to Scope.onError and the other bindings still
+   * run. A view can have several bindings; when two return the same name,
+   * the one bound later wins.
+   *
+   * Never throws. Writes that fail are not repeated until the value
+   * changes, and are reported to Scope.onError like a failed
+   * View.set (a value over the limits of PropValue: `limit`).
    * @capability That of the view: `ui.window`, `ui.mount` or `ui.settings`.
    * @param props - Returns the properties, by name.
    * @returns A handle that stops this binding (the values last sent stay).
+   * @example Show what is playing and whether it can seek
+   * The status window always shows the current file and enables its seek
+   * controls only for seekable sources. The SDK calls the function right
+   * away and again in every update pass (after player state changes and
+   * after each handler) and sends only the values that changed.
+   * ```ts
+   * const status = plugin.windows.create("ui/status.slint");
+   * status.bind(() => ({
+   *   title: plugin.player.state.source ?? "Nothing playing",
+   *   canSeek: plugin.player.state.can.seek,
+   * }));
+   * ```
    */
   bind(props: () => Props): Disposable;
 }
 ```
 
+Example: Wire a window's label and buttons to the plugin (examples/bookmark)
+
+A Bookmark window shows the saved position and two buttons that save
+it and jump back to it. `bind` keeps the label and the buttons' enabled
+state equal to the plugin's state: the SDK evaluates the function again
+after every handler and player change and sends only what changed. The
+buttons' Slint callbacks reach the plugin through `on`.
+
+```ts
+const window = plugin.windows.create("ui/bookmark.slint");
+// Re-evaluated after every handler and player change; only changes are sent.
+window.bind(() => ({
+  label: mark === null ? "No bookmark" : `Bookmark: ${mark.toFixed(1)} s`,
+  canMark: player.state.position !== null,
+  canJump: mark !== null && player.state.can.seek,
+}));
+// The Slint callbacks `mark` and `jump` of ui/bookmark.slint.
+window.on("mark", () => (mark = player.state.position));
+window.on("jump", () => player.seek(mark!));
+```
+
+`ui/bookmark.slint`:
+
+```slint
+import { Button, VerticalBox, HorizontalBox } from "std-widgets.slint";
+export component BookmarkWindow inherits Window {
+    title: "Bookmark";
+    preferred-width: 320px;
+    in property <string> label: "No bookmark";
+    in property <bool> can-mark;
+    in property <bool> can-jump;
+    callback mark();
+    callback jump();
+    VerticalBox {
+        Text { text: root.label; }
+        HorizontalBox {
+            Button { text: "Mark this position"; enabled: root.can-mark; clicked => { root.mark(); } }
+            Button { text: "Jump to bookmark"; enabled: root.can-jump; clicked => { root.jump(); } }
+        }
+    }
+}
+```
+
 ### Window
 
 A tool window: a separate operating-system window drawn from one of the
 plugin's `.slint` files, made by Windows.create.
 
+**What it is.** A top-level window with its own title bar: the user can
+move it, resize it (if the Slint file allows) and close it. It is not
+modal and not attached to the main window: playback and the main window
+keep working while it is open. Its title, size and content come from the
+Slint `Window` component (`title`, `width` or `preferred-width`…); the
+player applies its palette and the system font before the window appears.
+The system chooses its position; the player does not remember it.
+MainWindow.setAlwaysOnTop also floats tool windows.
+
+**Life cycle.**
+1. `create()` makes the handle; nothing is on screen.
+2. Bind callbacks with View.on and properties with
+   View.bind or View.set.
+3. Window.show opens the window with those properties.
+   Window.hide hides it and keeps its state.
+4. Window.close, or the user (title-bar button or the
+   standard close keys), destroys the window instance; only the
+   user's close calls Window.onClose. The handle stays usable: the
+   next `show()` opens a fresh instance with the current properties.
+5. `dispose()`, disposing the owning scope or the plugin stopping closes
+   it for good (without `onClose`); the id can then be used again.
+
+Command key bindings do not fire while a tool window has focus; handle
+keys in Slint (a `FocusScope`). The standard close keys never reach the
+window's Slint code.
+
+Testing: `host.window(id)` of `@vestra-player/sdk/testing` has the
+window's `props`, `visible`, `emit(callback, ...args)` and `userClose()`.
+
 - @capability ui.window
 
 ```ts
 interface Window extends View, Disposable {
   /**
    * Open the window, or show it again if it is hidden.
+   *
+   * When no window instance exists (the first call, or after a close), the
+   * player compiles the Slint file and opens a new window. Its initial
+   * properties are the bound values and the values last passed to
+   * View.set, so no default values flash, and the callbacks bound
+   * so far are registered. When the window is hidden, it is shown again with
+   * its state.
+   *
+   * `show`, `hide` and `close` of one window run one after another in call
+   * order. After `dispose()`, `show` does nothing.
    * @capability ui.window
    * @returns Resolves once the player has shown the window.
    * @throws capability (rejects) The manifest does not declare `ui.window`.
@@ -3941,20 +4681,72 @@ interface Window extends View, Disposable {
    * @throws host (rejects) The Slint file is missing, outside the package directory or does not compile; it exports more than one component; or a bound property or callback is not declared in it. `message` has the reason, including the compiler's diagnostics.
    * @throws missing (rejects) An image in the initial properties does not exist (see Ui.image).
    * @throws invalid (rejects) An image in the initial properties fails another check: outside the allowed directories, too large, not PNG or JPEG.
+   * @example Tell the user why a window did not open
+   * When the inspector cannot open, the user sees why on the OSD instead
+   * of nothing happening. `show` compiles the Slint file and opens the
+   * window; it rejects with a code, such as `host` for a Slint file that
+   * does not compile or `unavailable` without a user interface.
+   * ```ts
+   * const window = plugin.windows.create("ui/inspector.slint");
+   * try {
+   *   await window.show();
+   * } catch (error) {
+   *   // The code is data; `message` has the details for the log.
+   *   await plugin.osd.show("Cannot open the inspector ({})", [(error as PluginError).code]);
+   * }
+   * ```
    */
   show(): Promise<void>;
   /**
    * Hide the window without closing it.
+   *
+   * The instance and everything in it stay; Window.opened stays
+   * `true` and Window.show brings the window back as it was. Does
+   * nothing when the window is not open.
    * @capability ui.window
    * @returns Resolves once the window is hidden.
    * @throws missing (rejects) The user closed the window just before (the close had not reached the plugin yet).
+   * @example Show and hide a window from a checkable menu item
+   * Audio ▸ Levels shows the window with a check mark and hides it again.
+   * `hide` keeps the window's instance and state, so showing it again is
+   * instant; the check mark follows `visible`, and `onClose` resets it when
+   * the user closes the window with its title-bar button.
+   * ```ts
+   * const levels = plugin.windows.create("ui/levels.slint");
+   * let visible = false; // what the check mark shows
+   * plugin.commands.add({
+   *   id: "levels",
+   *   path: ["@audio", "Levels"],
+   *   checked: () => visible,
+   *   run: async () => {
+   *     visible = !visible;
+   *     await (visible ? levels.show() : levels.hide());
+   *   },
+   * });
+   * levels.onClose(() => (visible = false));
+   * ```
    */
   hide(): Promise<void>;
   /**
    * Close the window and destroy its instance; the handle stays usable.
+   *
+   * The next Window.show opens a fresh instance with the current
+   * properties; state that only the Slint side had (text the plugin did not
+   * record) is gone. Window.onClose is not called. Does nothing when
+   * the window is not open. Unlike `dispose()`, the handle, its handlers and
+   * its bindings stay.
    * @capability ui.window
    * @returns Resolves once the window is closed.
    * @throws missing (rejects) The user closed the window just before.
+   * @example Close the window from its own button
+   * The editor's Done button closes the editor window. `close` destroys
+   * the window instance but keeps the handle, its handlers and bindings,
+   * so the next `show` opens a fresh window; `onClose` is not called for
+   * the plugin's own close.
+   * ```ts
+   * const editor = plugin.windows.create("ui/editor.slint");
+   * editor.on("done", () => editor.close());
+   * ```
    */
   close(): Promise<void>;
   /**
@@ -3963,30 +4755,128 @@ interface Window extends View, Disposable {
   readonly opened: boolean;
   /**
    * Run code when the user closes the window.
+   *
+   * Called for the title-bar close button and the
+   * standard close keys. When it runs, the window
+   * instance is gone and Window.opened is already `false`; a later
+   * `show()` opens a fresh one. It is not called for the plugin's own
+   * Window.close or `dispose()`, nor when the plugin stops. Errors
+   * it throws go to Scope.onError, and an update pass follows.
+   *
+   * Stop what the window needed here: timers, polling, a live preview.
    * @capability ui.window
    * @param listener - Called with no arguments; may be async.
    * @returns A handle that removes the listener.
+   * @example Remember that the user closed the window
+   * The plugin records that the notes window was closed, so it does not
+   * reopen it at the next start. `onClose` runs for the title-bar button,
+   * the player's close keys (Cmd+W, Ctrl+W, Ctrl+F4) and the system's own
+   * close request such as Alt+F4 (not for the plugin's own `close`); the
+   * store writes the change to `window.json` shortly after.
+   * ```ts
+   * const store = plugin.storage.json("window", { defaults: { open: false } });
+   * const window = plugin.windows.create("ui/notes.slint");
+   * window.onClose(() => store.save({ open: false }));
+   * ```
    */
   onClose(listener: () => unknown): Disposable;
 }
 ```
 
+Example: Open a window from a menu command (examples/bookmark)
+
+Playback ▸ Bookmark… opens the Bookmark window. `create` only makes a
+handle; the command's `run` calls `show`, which compiles the Slint file
+and opens the window with the bound properties the first time, and
+brings back the same window afterwards.
+
+```ts
+const window = plugin.windows.create("ui/bookmark.slint");
+// Re-evaluated after every handler and player change; only changes are sent.
+window.bind(() => ({
+  label: mark === null ? "No bookmark" : `Bookmark: ${mark.toFixed(1)} s`,
+  canMark: player.state.position !== null,
+  canJump: mark !== null && player.state.can.seek,
+}));
+// The Slint callbacks `mark` and `jump` of ui/bookmark.slint.
+window.on("mark", () => (mark = player.state.position));
+window.on("jump", () => player.seek(mark!));
+
+plugin.commands.add({
+  id: "bookmark.open",
+  path: ["@playback", "Bookmark…"],
+  order: 270,
+  run: () => window.show(), // opens it, or brings back the open one
+});
+```
+
+Example: Stop work when the user closes the window
+
+A clock window ticks every second while it is open and stops costing
+anything once the user closes it. `plugin.update()` makes the SDK
+evaluate the bound time again from a timer; `onClose` runs only for the
+user's close, so the plugin stops the timer there.
+```ts
+const clock = plugin.windows.create("ui/clock.slint");
+let timer: NodeJS.Timeout | undefined;
+clock.bind(() => ({ time: new Date().toLocaleTimeString() }));
+clock.onClose(() => {
+  clearInterval(timer);
+  timer = undefined;
+});
+plugin.commands.add({
+  id: "clock",
+  path: ["@screen", "Clock…"],
+  run: async () => {
+    await clock.show();
+    // Re-evaluate `bind` once a second: bound values change only then.
+    timer ??= setInterval(() => plugin.update(), 1000);
+  },
+});
+```
+
 ### Windows
 
 Create tool windows: separate windows drawn from the plugin's `.slint`
 files. `plugin.windows`.
 
+Use a tool window for something the user opens, works with and closes: a
+picture adjustment panel, an inspector, an editor. For content that should
+stay inside the player's main window, mount a panel; for
+preferences, add a settings page; for a yes/no
+question, use Dialogs.confirm. A plugin can have any number of
+windows.
+
 - @capability ui.window
 
 ```ts
 interface Windows {
   /**
    * Create a window handle for a `.slint` file; nothing opens until Window.show.
+   *
+   * The file must export exactly one component, usually
+   * `export component Name inherits Window`; helper components without
+   * `export` are allowed. The window's properties and callbacks are declared
+   * on that component. The file is not read here: a missing or broken file
+   * makes Window.show reject.
+   *
+   * Bind every callback with View.on before the first `show()`.
    * @capability ui.window (checked by Window.show).
    * @param file - Path relative to the package directory, with `/` on every system, for example `"ui/picture.slint"`. It must stay inside the package.
    * @param options - `id`: the window's name, unique among this plugin's windows until the window is disposed. Default: the file name without its extension (`ui/picture.slint` → `picture`). Give distinct ids to open the same file more than once.
    * @returns A Window owned by this scope.
    * @throws conflict (throws) This plugin already has a window with this id (SDK 1.3.0; before, a plain `Error` without `code`).
+   * @example Open two windows from one Slint file
+   * Two compare windows open side by side, one labelled A and one B. A
+   * window's id defaults to its file name, so the second window of the
+   * same file needs its own `id`; each handle has its own properties.
+   * ```ts
+   * const left = plugin.windows.create("ui/compare.slint", { id: "compare-left" });
+   * const right = plugin.windows.create("ui/compare.slint", { id: "compare-right" });
+   * left.set({ side: "A" });
+   * right.set({ side: "B" });
+   * await Promise.all([left.show(), right.show()]);
+   * ```
    */
   create(file: string, options?: {
     id?: string;
@@ -3994,6 +4884,32 @@ interface Windows {
 }
 ```
 
+Example: Create a window and open it from a menu (examples/bookmark)
+
+A Bookmark window opens from Playback ▸ Bookmark…. `create` returns a
+handle without opening anything; its bindings and callbacks are set up
+first, and `show` opens the window when the command runs.
+
+```ts
+const window = plugin.windows.create("ui/bookmark.slint");
+// Re-evaluated after every handler and player change; only changes are sent.
+window.bind(() => ({
+  label: mark === null ? "No bookmark" : `Bookmark: ${mark.toFixed(1)} s`,
+  canMark: player.state.position !== null,
+  canJump: mark !== null && player.state.can.seek,
+}));
+// The Slint callbacks `mark` and `jump` of ui/bookmark.slint.
+window.on("mark", () => (mark = player.state.position));
+window.on("jump", () => player.seek(mark!));
+
+plugin.commands.add({
+  id: "bookmark.open",
+  path: ["@playback", "Bookmark…"],
+  order: 270,
+  run: () => window.show(), // opens it, or brings back the open one
+});
+```
+
 ### SlotState
 
 The state of the bottom bar or sidebar position, whoever mounted the
@@ -4066,6 +4982,16 @@ interface PanelState {
 The bottom bar or the sidebar position (`plugin.panels.bottom`,
 `plugin.panels.sidebar`), independent of who mounted the panel there.
 
+The position does not belong to the plugin that mounted the panel: any
+plugin with `ui.mount` may read and toggle it, so a "Show playlist" command
+can live in a different plugin than the playlist. The player remembers
+the sidebar's visibility, width, detached state and floating window
+position across launches.
+
+`state` is read when first used. With `events` it then follows every
+change (the user, other plugins, the window size); without `events` it
+refreshes only after this plugin's own changes.
+
 - @capability ui.mount; `events` to follow changes made elsewhere.
 
 ```ts
@@ -4081,48 +5007,138 @@ interface PanelSlot {
   readonly panels: readonly SlotPanel[] | null;
   /**
    * Run code when the position's state changes.
+   *
+   * Needs `events`: without it the listener runs only after this plugin's own
+   * changes. Called with `null` when the panel there is unmounted, and also
+   * when only the tabs changed (PanelSlot.panels: a panel added or
+   * removed, another tab current). Errors go to Scope.onError.
    * @capability ui.mount and events
    * @param listener - Receives the new state.
    * @returns A handle that removes the listener.
+   * @example Tell the user when the window is too narrow for the sidebar
+   * When the sidebar should show but the window has no room for it, the
+   * OSD says so. With `events`, the listener runs on every change of the
+   * position, whoever caused it. The player reports `reason: "space"` when
+   * the preference is to show the sidebar but the window is too small.
+   * ```ts
+   * plugin.panels.sidebar.onChange((state) => {
+   *   // `null`: no panel is mounted in the sidebar any more.
+   *   if (state?.reason === "space") void plugin.osd.show("Widen the window to see the playlist");
+   * });
+   * ```
    */
   onChange(listener: (state: SlotState | null) => void): Disposable;
   /**
    * Show or hide the panel at this position: set the user's preference.
+   *
+   * The same as the user's menu item: the preference is remembered. Showing
+   * may still leave the panel off screen (`reason: "space"`); in fullscreen,
+   * `true` pops the sidebar overlay out at once.
    * @capability ui.mount
    * @param visible - The new preference.
    * @returns Resolves once the layout has the new preference, with `state` refreshed.
    * @throws missing (rejects) No panel is mounted at this position.
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws capability (rejects) The manifest does not declare `ui.mount`.
+   * @example Hide the bottom bar for a clean picture
+   * The control bar disappears, as if the user had hidden it from the menu,
+   * and stays hidden at the next start because the preference is
+   * remembered. `setVisible` rejects with `missing` when no panel is in the
+   * bottom bar, which this plugin treats as nothing to hide.
+   * ```ts
+   * await plugin.panels.bottom.setVisible(false).catch((error: PluginError) => {
+   *   if (error.code !== "missing") throw error; // no bar mounted: nothing to do
+   * });
+   * ```
    */
   setVisible(visible: boolean): Promise<void>;
   /**
    * Flip the user's preference, using the player's current value.
+   *
+   * Reads the state from the player first, so it is right even without
+   * `events`.
    * @capability ui.mount
    * @returns Resolves once the layout has the new preference.
    * @throws missing (rejects) No panel is mounted at this position.
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws capability (rejects) The manifest does not declare `ui.mount`.
+   * @example Toggle the control bar from a checkable menu item
+   * Screen ▸ Control bar shows or hides the bottom bar and carries a check
+   * mark while it is shown. `toggle` reads the player's current preference
+   * first, so it is right even without `events`; `checked` is evaluated
+   * again after the command runs and follows `state`.
+   * ```ts
+   * plugin.commands.add({
+   *   id: "toggle-bar",
+   *   path: ["@screen", "Control bar"],
+   *   // The user's preference, remembered across launches.
+   *   checked: () => plugin.panels.bottom.state?.preferred ?? false,
+   *   run: () => plugin.panels.bottom.toggle(),
+   * });
+   * ```
    */
   toggle(): Promise<void>;
   /**
    * Make a panel's tab the current one, without showing or hiding the position.
+   *
+   * The sidebar holds the panels of several plugins as tabs (see
+   * Panels.mount); this switches which one it shows, like a click on
+   * its tab. To show this plugin's own panel, use Panel.show. The
+   * bottom bar has one panel: activating it changes nothing. Players
+   * without sidebar tabs (0.4.0 and older) ignore it.
    * @capability ui.mount
    * @param plugin - The manifest id of the plugin whose panel to show, one of PanelSlot.panels.
    * @returns Resolves once the layout has the new current tab, with `state` refreshed.
    * @throws missing (rejects) No panel is mounted at this position, or none of `plugin`.
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws capability (rejects) The manifest does not declare `ui.mount`.
+   * @example Switch the sidebar to the playlist's tab
+   * A command makes the playlist the sidebar's current tab without showing
+   * or hiding the sidebar, like a click on its tab. `activate` takes the
+   * manifest id of the plugin whose tab to show and rejects with
+   * `missing` when that plugin has no panel there.
+   * ```ts
+   * plugin.commands.add({
+   *   id: "to-playlist",
+   *   title: "Show the playlist tab",
+   *   run: () => plugin.panels.sidebar.activate("vestra.playlist"),
+   * });
+   * ```
    */
   activate(plugin: string): Promise<void>;
 }
 ```
 
+Example: Add a "Show sidebar" item that works with any sidebar panel
+
+Tools ▸ Show sidebar shows or hides the sidebar, whichever plugin's
+panel is in it, with a check mark while it is shown. The position does
+not belong to the plugin that mounted the panel: `state` is `null`
+while nobody has a panel there (the item is disabled then), and
+`toggle` flips the user's remembered preference.
+```ts
+const sidebar = plugin.panels.sidebar;
+plugin.commands.add({
+  id: "sidebar",
+  path: ["Tools", "Show sidebar"],
+  // `state` is null while no plugin has a panel in the sidebar.
+  checked: () => sidebar.state?.preferred ?? false,
+  enabled: () => sidebar.state !== null,
+  run: () => sidebar.toggle(),
+});
+```
+
 ### SidebarSlot
 
 The sidebar position: a PanelSlot that can also float in a window
 of its own.
 
+Detached, the sidebar panel is shown in a separate window (300×408 by
+default, at least 300×250) with the panel's `title`. The plugin's
+properties and callbacks stay the same, but the window holds a new
+instance of the component. Closing the floating window (its close button
+or the standard close keys) is the same as `setVisible(false)`.
+
 - @capability ui.mount
 
 ```ts
@@ -4135,21 +5151,76 @@ interface SidebarSlot extends PanelSlot {
    * @throws missing (rejects) No panel is mounted in the sidebar.
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws capability (rejects) The manifest does not declare `ui.mount`.
+   * @example Float the sidebar or dock it back
+   * The sidebar moves into its own window, or back into the main window
+   * when it already floats. `state` says whether it is detached now;
+   * `setDetached` resolves once the layout changed, with `state` refreshed.
+   * ```ts
+   * const sidebar = plugin.panels.sidebar;
+   * await sidebar.setDetached(!sidebar.state?.detached);
+   * ```
    */
   setDetached(detached: boolean): Promise<void>;
 }
 ```
 
+Example: Add a "Detach sidebar" item
+
+Tools ▸ Detach sidebar floats the sidebar in its own window and docks
+it again, with a check mark while it floats. `setDetached` moves all
+the sidebar's tabs; the floating window holds new instances of the
+panels, which keep the plugins' properties and callbacks.
+```ts
+const sidebar = plugin.panels.sidebar;
+plugin.commands.add({
+  id: "detach",
+  path: ["Tools", "Detach sidebar"],
+  // Detaching moves every tab of the sidebar into the floating window.
+  checked: () => sidebar.state?.detached ?? false,
+  enabled: () => sidebar.state !== null,
+  run: () => sidebar.setDetached(!sidebar.state?.detached),
+});
+```
+
 ### Panel
 
 A panel in the player's main window, made by Panels.mount.
 
+Properties and callbacks live on the file's bridge global (see
+Panels). Unlike a tool window, a panel forwards every callback of
+the global, so View.on has no "bind before show" rule.
+
+**Life cycle.** `mount()` returns at once; in the next microtask the SDK
+sends the mount with every property bound or set so far. The player queues
+mounts and rebuilds its main window with the panel; Panel.ready
+then resolves. Rebuilding happens whenever any plugin mounts or unmounts a
+panel, and detaching the sidebar puts a new instance in a floating window.
+The player restores the bridge properties to the values last written, but
+state kept only inside the component (a scroll position, a property the
+plugin never writes) starts over: keep what matters in bridge properties.
+`dispose()`, disposing the scope or stopping the plugin unmounts it.
+
+Testing: `host.mounted()` of `@vestra-player/sdk/testing` has the panel's
+`slot`, `props` and `emit(callback, ...args)`.
+
 - @capability ui.mount
 
 ```ts
 interface Panel extends View, Disposable {
   /**
    * Resolves once the player has mounted the panel and the main window shows it; rejects when the mount failed.
+   *
+   * Mounts made while `activate` runs must succeed before the plugin is
+   * ready: a rejection fails activation, except `conflict` for a taken
+   * position (below), which the player (0.4.x after 0.4.0) and `TestHost`
+   * do not count: the plugin runs without its panel, its commands and keys
+   * work, and the player shows the refusal (an OSD message,
+   * PluginInfo.warnings and the text in PluginInfo.error).
+   * Later failures also go to Scope.onError.
+   *
+   * A second sidebar panel is not refused: it resolves as another tab
+   * (see Panel.state). Built-in plugins mount first at start-up,
+   * so the playlist's tab is first and a built-in panel keeps its position.
    * @throws ui-prepare (rejects) The Slint file does not compile, or a bound property is not declared on the bridge global; `message` has the diagnostics. (Players 0.4.0 and older also answer a taken bottom bar or sidebar with it.)
    * @throws conflict (rejects) Another plugin's panel holds the bottom bar or the backdrop (shown, or being mounted), or the sidebar has all the tabs it takes (8); `message` names the position and the holder (「侧栏已被 vestra.playlist 使用」). Not an activation failure.
    * @throws busy (rejects) The player is still preparing this plugin's previous mount, or its queue of mounts is full.
@@ -4161,38 +5232,117 @@ interface Panel extends View, Disposable {
   readonly ready: Promise<void>;
   /**
    * This panel's state: its position's, and whether its tab is the current one; `null` until Panel.ready resolved (and after `dispose`).
+   *
+   * Read when first used; with `events` it then follows every change (the
+   * user switching tabs, other plugins, the window size), without `events`
+   * only this plugin's own changes. A sidebar panel in a background tab
+   * has `active: false`, `effective: false` and `reason: "otherTab"`.
    * @throws Never; `null` stands for "not mounted".
    */
   readonly state: PanelState | null;
   /**
    * Run code when this panel's state changes.
+   *
+   * Needs `events`: without it the listener runs only after this plugin's
+   * own changes. Called with `null` when the panel is unmounted. Errors go
+   * to Scope.onError.
    * @capability ui.mount and events
    * @param listener - Receives the new state.
    * @returns A handle that removes the listener.
+   * @example Notice when the list moves to a background tab
+   * The plugin logs when the user switches the sidebar to another plugin's
+   * tab, for example to pause work the list does. With `events` the
+   * listener runs on every change. `reason: "otherTab"` exists only in a
+   * panel's own state: the SDK sets it when the sidebar's current tab is
+   * another plugin's (the position's state never has it).
+   * ```ts
+   * const panel = plugin.panels.mount("sidebar", "ui/list.slint", { title: "List" });
+   * panel.onChange((state) => {
+   *   if (state?.reason === "otherTab") console.error("list in a background tab");
+   * });
+   * ```
    */
   onChange(listener: (state: PanelState | null) => void): Disposable;
   /**
    * Show this panel: make its tab the current one and show its position.
+   *
+   * Sets the position's preference like PanelSlot.setVisible`(true)`
+   * (remembered; in fullscreen the sidebar overlay pops out). On players
+   * without sidebar tabs (0.4.0 and older) it is just that. Waits for
+   * Panel.ready first.
    * @capability ui.mount
    * @returns Resolves once the layout shows the panel's tab, with `state` refreshed.
    * @throws invalid (rejects) The panel is the backdrop, which the player shows by itself.
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws The errors of Panel.ready (rejects) The mount failed.
+   * @example Bring the plugin's sidebar panel to the front
+   * A command shows the List tab: it becomes the current tab and the
+   * sidebar is shown, and the preference is remembered. `show` waits for
+   * the mount first, so it can run right after `mount`.
+   * ```ts
+   * const list = plugin.panels.mount("sidebar", "ui/list.slint", { title: "List" });
+   * plugin.commands.add({ id: "show", title: "Show the list", run: () => list.show() });
+   * ```
    */
   show(): Promise<void>;
   /**
    * Show this panel, or hide its position when it is shown.
+   *
+   * Reads the state from the player first. When the position is shown
+   * (`preferred`) and this panel's tab is the current one, it hides the
+   * position; otherwise it does Panel.show: a panel in a background
+   * tab comes to the front instead of the sidebar closing. A "Show list"
+   * command checked by `state.preferred && state.active` matches it. Waits
+   * for Panel.ready first.
    * @capability ui.mount
    * @returns Resolves once the layout has changed, with `state` refreshed.
    * @throws invalid (rejects) The panel is the backdrop.
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws The errors of Panel.ready (rejects) The mount failed.
+   * @example Toggle a sidebar panel with F6, like the playlist
+   * F6 and Screen ▸ List show the List tab, or hide the sidebar when the
+   * list is already in front. `toggle` reads the player's state first:
+   * it hides the position only when it is shown and this panel's tab is
+   * the current one, otherwise it shows the panel.
+   * ```ts
+   * const list = plugin.panels.mount("sidebar", "ui/list.slint", { title: "List" });
+   * plugin.commands.add({
+   *   id: "list",
+   *   path: ["@screen", "List"],
+   *   bindings: ["F6"],
+   *   // Checked while the sidebar is shown with this list in front.
+   *   checked: () => (list.state?.preferred ?? false) && (list.state?.active ?? false),
+   *   run: () => list.toggle(),
+   * });
+   * ```
    */
   toggle(): Promise<void>;
   /**
    * Keep the panel on screen while the user works in it.
+   *
+   * In fullscreen the bottom bar shows only while the pointer is in the bar's
+   * own band at the bottom of the screen: at once when the pointer enters it,
+   * hidden 500 ms after it leaves (player 0.5.1; keys and pointer motion
+   * elsewhere do not reveal it), and the fullscreen sidebar overlay collapses
+   * when the pointer leaves it. A lock keeps the bar shown. Set a
+   * lock while a text field has focus, a drag is in progress or a popup is
+   * open, and clear it afterwards. Locks are merged with the earlier ones;
+   * the last value of each wins. The player already locks a panel while the
+   * pointer is over it. No effect on the backdrop.
+   *
+   * Never throws: a failed write is reported to Scope.onError.
    * @capability ui.mount
    * @param locks - The locks to change; omitted ones keep their value.
+   * @example Keep the bar on screen while a search field has focus
+   * In fullscreen the bottom bar stays visible while the user types in
+   * its search field, instead of hiding when the pointer leaves it. The
+   * Slint side reports the field's focus through a callback, and
+   * `setInteraction` sets or clears the `focused` lock; other locks keep
+   * their values.
+   * ```ts
+   * const panel = plugin.panels.mount("bottom", "ui/bar.slint");
+   * panel.on("searchFocused", (focused: boolean) => panel.setInteraction({ focused }));
+   * ```
    */
   setInteraction(locks: Partial<{
     /** A text field (or another control taking keys) has focus. */
@@ -4204,6 +5354,12 @@ interface Panel extends View, Disposable {
   }>): void;
   /**
    * Pop up a menu of this plugin's commands at a point in the panel.
+   *
+   * A one-level menu, styled like the main menu (check marks, shortcut text),
+   * in the window that shows the panel. Picking an item runs that command;
+   * `null` is a separator. Commands without a menu `path` work too, which
+   * makes context-only commands possible. Call it when the right button is
+   * released, as the main menu does. Waits for Panel.ready first.
    * @capability ui.mount
    * @param items - At most 32 commands of this plugin, or `null` for a separator.
    * @param at - Where to open it, in the window's logical pixels: in Slint, `(self.absolute-position.x + self.mouse-x) / 1px` (and the same for `y`).
@@ -4212,6 +5368,20 @@ interface Panel extends View, Disposable {
    * @throws unavailable (rejects) The panel is not on screen (also: its sidebar tab is not the current one), or it is the backdrop.
    * @throws invalid (rejects) No items, more than 32, or `at` is not finite.
    * @throws The errors of Panel.ready (rejects) The mount failed.
+   * @example Open a context menu where the user right-clicked (examples/panel-menu)
+   * Right-clicking the list opens a menu with "Select the first item" and
+   * "Remove the selected item". The Slint file passes the pointer position
+   * in window pixels with its `context-menu` callback; `showMenu` opens the
+   * plugin's commands there, and picking one runs that command.
+   *
+   * ```ts
+   * // Callbacks of the bridge global; `bind` above sends the new selection.
+   * panel.on("select", (index: number) => (selected = index));
+   * // x and y: the pointer in window pixels, from the Slint file.
+   * panel.on("contextMenu", (x: number, y: number) =>
+   *   panel.showMenu([first, null, remove], { x, y }),
+   * );
+   * ```
    */
   showMenu(items: (Command | null)[], at: {
     /** Logical pixels from the window's left edge. */
@@ -4221,9 +5391,29 @@ interface Panel extends View, Disposable {
   }): Promise<void>;
   /**
    * Receive the files dropped on this panel.
+   *
+   * Covers the docked panel and the floating sidebar window. While a listener
+   * exists, drops on the panel come here as one group (not split by
+   * extension) instead of going to the Drops providers. Drops on
+   * tool windows and the Options window are ignored; in fullscreen, the
+   * bottom bar floats over the video and drops there count as drops on the
+   * video area.
    * @capability ui.drop
    * @param listener - Receives the paths in the order the file manager gave them, the point in panel coordinates (logical pixels from the panel's top-left corner) and the keys held.
    * @returns A handle that removes the listener.
+   * @example Add dropped files to a list
+   * Files dropped on the Files panel are added to its list. While the
+   * listener exists, drops on the panel come here as one group instead of
+   * going to the drop providers; after the listener returns, the SDK runs
+   * an update pass and `bind` sends the longer list.
+   * ```ts
+   * const files: string[] = [];
+   * const panel = plugin.panels.mount("sidebar", "ui/list.slint", { title: "Files" });
+   * panel.bind(() => ({ rows: files }));
+   * panel.onDrop(({ paths }) => {
+   *   files.push(...paths); // in the order the file manager gave them
+   * });
+   * ```
    */
   onDrop(listener: (event: {
     /** Absolute paths of the dropped files and folders. */
@@ -4239,6 +5429,74 @@ interface Panel extends View, Disposable {
 }
 ```
 
+Example: Mount a sidebar list with a right-click menu (examples/panel-menu)
+
+The sidebar gets an "Example list" tab whose rows can be selected and
+have a context menu. `mount` returns at once and the player adds the
+panel when it rebuilds its main window; `bind` keeps the rows and the
+selection on the panel's bridge global, and the `context-menu` callback
+opens a menu of the plugin's commands where the user clicked.
+
+```ts
+const panel = plugin.panels.mount("sidebar", "ui/panel.slint", {
+  title: "Example list",
+});
+// Sent when the panel mounts, then whenever a value changes.
+panel.bind(() => ({ rows: items, selected }));
+
+// Callbacks of the bridge global; `bind` above sends the new selection.
+panel.on("select", (index: number) => (selected = index));
+// x and y: the pointer in window pixels, from the Slint file.
+panel.on("contextMenu", (x: number, y: number) =>
+  panel.showMenu([first, null, remove], { x, y }),
+);
+```
+
+`ui/panel.slint`:
+
+```slint
+import { Theme } from "@vestra/theme.slint";
+
+export global ListBridge {
+    in property <[string]> rows;
+    in property <int> selected;
+    callback select(int);
+    callback context-menu(float, float);
+}
+
+export component ListPanel inherits Rectangle {
+    background: Theme.bg-list;
+    min-width: 200px;
+    VerticalLayout {
+        for row[index] in ListBridge.rows: Rectangle {
+            height: 20px;
+            background: index == ListBridge.selected ? Theme.selected-bg : transparent;
+            Text {
+                x: 6px;
+                text: (index + 1) + ". " + row;
+                color: index == ListBridge.selected ? Theme.text : Theme.text-list;
+                font-size: Theme.font-body;
+                vertical-alignment: center;
+            }
+            TouchArea {
+                pointer-event(event) => {
+                    if event.kind == PointerEventKind.down {
+                        ListBridge.select(index);
+                    }
+                    if event.kind == PointerEventKind.up && event.button == PointerEventButton.right {
+                        ListBridge.context-menu((self.absolute-position.x + self.mouse-x) / 1px,
+                            (self.absolute-position.y + self.mouse-y) / 1px);
+                    }
+                }
+            }
+        }
+        // Takes the space below the rows. Without it the layout's maximum
+        // height (three 20px rows) would cap the player's main window.
+        Rectangle { vertical-stretch: 1; }
+    }
+}
+```
+
 ### DropModifiers
 
 Keys held when the files were dropped.
@@ -4280,9 +5538,30 @@ interface Drops {
    * Take files dropped on the video area. The first provider registered for
    * an extension gets it; files nobody takes are ignored.
    *
-   * Paths are grouped by extension (case-insensitive) in the order the file
+   * Paths are grouped by provider (an extension, case-insensitive, belongs
+   * to the provider that registered it first) in the order the file
    * manager gave them, one call per provider. Folders are not expanded.
    * @throws invalid synchronously for malformed extensions.
+   * @example Load dropped subtitle files
+   * Dropping .srt or .ass files on the video loads each one as a subtitle
+   * track. Each extension belongs to the provider that registered it first;
+   * the player groups the dropped paths by provider and calls each provider
+   * once with all of its paths, so .srt and .ass files dropped together
+   * arrive in one call. (A panel under the pointer that listens with
+   * `onDrop` takes the whole drop first.) The plugin reads each file itself
+   * and uploads its bytes with `subtitles.load`.
+   * ```ts
+   * plugin.drops.provide({
+   *   extensions: ["srt", "ass"],
+   *   drop: async ({ paths }) => {
+   *     // Only .srt and .ass files reach this provider.
+   *     for (const path of paths)
+   *       await plugin.subtitles.load(await readFile(path), {
+   *         format: path.endsWith(".ass") ? "ass" : "srt",
+   *       });
+   *   },
+   * });
+   * ```
    */
   provide(handler: DropHandler): Disposable;
 }
@@ -4295,6 +5574,10 @@ The player's palettes: `vestra`, the dark default, and `vestra-light`
 Both draw on the logo's colours. Read colours from `Theme` instead of
 branching on the id: a later version may add palettes.
 
+The player treats an id it does not have as `vestra`: plugins built with an
+older SDK that still ask for a palette removed in SDK 1.4.0 keep working,
+and a player older than 0.4.0 answers `vestra-light` with `vestra`.
+
 ```ts
 type ThemeId = "vestra" | "vestra-light";
 ```
@@ -4303,6 +5586,19 @@ type ThemeId = "vestra" | "vestra-light";
 
 The player's palette, which every view uses. `plugin.appearance`.
 
+The player sets the palette on every view (the main window and its panels,
+the floating sidebar, tool windows, the Options window) before it appears
+and again when the palette changes. Slint code that reads its colours from
+`Theme` (`import { Theme } from "@vestra/theme.slint"`) follows it with no
+plugin code; hard-coded colours do not. Only colours change: corner radii,
+font sizes and control sizes are the same in every palette. A light palette
+also switches the std-widgets controls (`std-widgets.slint`) to their light
+colours, and keeps the video area dark.
+
+The player saves the choice; it stays after the plugin that set it stops.
+Tell the user about a change yourself (for example with
+Osd.show).
+
 - @capability None to read `theme`; `events` to follow changes; `ui.theme` to change it.
 
 ```ts
@@ -4311,24 +5607,62 @@ interface Appearance {
   readonly theme: ThemeId;
   /**
    * Run code when the palette changes.
+   *
+   * Needs `events`: without it the listener never runs for other plugins'
+   * changes. Views need no help to follow the palette; use this for things
+   * the plugin draws itself (a rendered image, colours it computes). Errors
+   * go to Scope.onError.
    * @capability events
    * @param listener - Receives the new palette.
    * @returns A handle that removes the listener.
+   * @example Redraw a picture the plugin renders when the palette changes
+   * The plugin renders a chart image in the palette's colours and draws it
+   * again when the user or another plugin switches palettes. Views that use
+   * `Theme` follow on their own; this listener (which needs `events`) is
+   * for what the plugin draws itself.
+   * ```ts
+   * plugin.appearance.onChange((theme) => {
+   *   void renderChart(theme === "vestra"); // the dark default
+   * });
+   * ```
    */
   onChange(listener: (theme: ThemeId) => void): Disposable;
   /**
    * Switch the palette of every view.
+   *
+   * The player applies it to every open view without interrupting a drag or
+   * an open menu, and saves it across restarts.
    * @capability ui.theme
    * @param theme - The palette to use.
    * @returns Resolves once the player has accepted the change; Appearance.theme has the new value.
    * @throws invalid (rejects) `theme` is not a ThemeId.
    * @throws capability (rejects) The manifest does not declare `ui.theme`.
+   * @example Switch to the light palette
+   * Every view of the player turns light, and stays light after a restart.
+   * The player applies the palette to every open view and saves the
+   * choice; when the promise resolves, `appearance.theme` already has the
+   * new value. Without `ui.theme` it rejects with `capability`.
+   * ```ts
+   * await plugin.appearance.set("vestra-light");
+   * ```
    */
   set(theme: ThemeId): Promise<void>;
-  /** The saved interface language: `"system"` (follow the system's languages, the default) or a Locale. */
+  /**
+   * The saved interface language: `"system"` (follow the system's languages, the default) or a Locale.
+   *
+   * This is the choice for the next start. The language of this run is
+   * I18n.locale and never changes while the player runs. Read before
+   * activation; with `events` it follows other plugins' changes, without it
+   * only this plugin's own. Players before 0.4.3 report `"system"`.
+   */
   readonly language: LanguagePreference;
   /**
    * Save the interface language for the next start.
+   *
+   * The player keeps the choice in its interface state; the language
+   * changes when the player starts again (tell the user, for example "Takes
+   * effect after restart"). Every plugin with `events` hears the change in
+   * Appearance.language.
    * @capability ui.theme
    * @player 0.4.3
    * @param language - `"system"` or a Locale.
@@ -4336,17 +5670,45 @@ interface Appearance {
    * @throws invalid (rejects) `language` is not `"system"` or a Locale.
    * @throws capability (rejects) The manifest does not declare `ui.theme`.
    * @throws unsupported (rejects) A player before 0.4.3.
+   * @example Choose German for the next start
+   * The player will start in German next time, and the user is told so.
+   * `setLanguage` only saves the choice: the language of this run
+   * (`i18n.locale`) never changes while the player runs. Players before
+   * 0.4.3 reject it with `unsupported`.
+   * ```ts
+   * await plugin.appearance.setLanguage("de");
+   * await plugin.osd.show("Takes effect after restart"); // translated by the player
+   * ```
    */
   setLanguage(language: LanguagePreference): Promise<void>;
 }
 ```
 
+Example: Offer the light palette as a menu item
+
+Settings ▸ Light colours switches every view of the player to the light
+palette and carries a radio mark while it is in use. `set` asks the
+player to switch (it saves the choice); `theme` holds the palette in use,
+and `checked` reads it again after every handler.
+```ts
+plugin.commands.add({
+  id: "light-colours",
+  path: ["@settings", "Light colours"],
+  radio: true, // a round mark instead of a check mark
+  checked: () => plugin.appearance.theme === "vestra-light",
+  run: () => plugin.appearance.set("vestra-light"),
+});
+```
+
 ### Locale
 
 An interface language of the player: English (`en`, the source language
 of every plugin text) or a translation. The list is `LOCALES` in
 `@vestra-player/sdk/testing`.
 
+Simplified Chinese is `zh-Hans`. There is no Traditional Chinese: a
+system set to Traditional Chinese (Taiwan, Hong Kong, Macao) gets English.
+
 ```ts
 type Locale = "en" | "zh-Hans" | "ja" | "ko" | "de" | "fr" | "es";
 ```
@@ -4380,6 +5742,18 @@ A text the player translates with the plugin's catalog and fills in:
 English source text with its arguments. Made by I18n.text; plain
 data, not a translation (the plugin never sees the translated string).
 
+Accepted wherever the player shows a plugin's text: command titles, path
+segments and reasons, Osd.show and OsdPanel.set (as the
+text or an argument), the texts of Dialogs.confirm, file dialog
+titles and `saveFile`'s `fileName`, and property values where Slint
+expects a `string` (at any depth: a `[string]` model, a struct field).
+Nested in another text's arguments it is translated too. Requires player
+0.4.3. Limits: `TEXT_LIMITS` in `@vestra-player/sdk/testing`.
+
+The wire form `{ $vestraText, args }` is what the player reads; write it
+with I18n.text, so that `vestra-plugin i18n extract` finds the
+source text.
+
 ```ts
 interface Text {
   /** The English source text: a template with `{}`, `{0}` or `{name}`. */
@@ -4445,6 +5819,30 @@ type TextValue = string | Text | TextList;
 
 The interface language of this run. `plugin.i18n`.
 
+Plugins write no translation code. Every user-visible text is English
+source text in one of three places, and the player translates it with
+the plugin's own catalog (`locales/<lang>.po`, compiled into the package
+by `vestra-plugin build`):
+
+1. declarations: command titles and paths, settings page and panel
+   titles, the manifest's `name`, `punchline`, `description` and `tags`;
+2. Slint: `@tr("…")` in the plugin's `.slint` files;
+3. sentences the plugin hands the player: Osd.show,
+   OsdPanel.set and Dialogs.confirm take a template and
+   its arguments (`osd.show("Speed {}×", [rate])`), never a sentence
+   composed in TypeScript.
+
+Where words and data cannot be separated that way (a menu item with a
+number, a `[string]` model, a sentence made of translated parts), the
+plugin passes a text value (I18n.text, I18n.list; SDK
+1.5.11): data the player translates, never a translated string.
+
+The language is fixed when the player starts: I18n.locale never
+changes during a run. Read it for what is not text, such as the order of
+names or a date format. `vestra-plugin i18n extract` collects the texts
+into `locales/messages.pot`; see the
+i18n guide.
+
 - @capability None.
 
 ```ts
@@ -4469,6 +5867,27 @@ interface I18n {
    * @param args - Values for its placeholders.
    * @throws invalid A malformed or over-limit value (`TEXT_LIMITS`).
    * @capability None.
+   * @example Fill a drop-down with fixed words and data
+   * The drop-down lists "No Audio" and one "Track 7 · en" entry per track,
+   * in the user's language. A `[string]` model may hold `text()` values: the
+   * player translates each source text with the plugin's catalog and fills
+   * in its arguments, so the plugin never composes translated strings.
+   * ```ts
+   * const { text } = plugin.i18n;
+   * const picker = plugin.windows.create("ui/clip.slint");
+   * const tracks = [{ id: 7, title: "en" }];
+   * // Each entry is translated, then filled in: "Track 7 · en".
+   * picker.set({
+   *   labels: [text("No Audio"), ...tracks.map((t) => text("Track {} · {}", [t.id, t.title]))],
+   * });
+   * ```
+   * @example Build a message from translated parts
+   * The OSD says "Download failed: Connection timed out", both parts in the
+   * user's language. An argument made with `text()` is translated too,
+   * while string arguments are shown as they are.
+   * ```ts
+   * await plugin.osd.show("Download failed: {}", [plugin.i18n.text("Connection timed out")]);
+   * ```
    */
   text(source: string, args?: TemplateArgs): Text;
   /**
@@ -4477,6 +5896,15 @@ interface I18n {
    * @param style - `"list"` by default.
    * @throws invalid A malformed or over-limit value.
    * @capability None.
+   * @example List file names the way the language joins them
+   * The OSD says "Removed missing shaders: a.glsl, b.glsl" in English and
+   * joins the names with "、" in Chinese. `list` makes a value the player
+   * joins per interface language; the names themselves are data and stay
+   * as they are.
+   * ```ts
+   * const missing = ["a.glsl", "b.glsl"];
+   * await plugin.osd.show("Removed missing shaders: {}", [plugin.i18n.list(missing)]);
+   * ```
    */
   list(items: readonly TextArg[], style?: ListStyle): TextList;
   /**
@@ -4485,6 +5913,25 @@ interface I18n {
    * @param args - Values for its placeholders.
    * @throws invalid A malformed or over-limit value.
    * @capability None.
+   * @example Fail an open with a message the user can read
+   * Opening a `.ch8` file the plugin cannot load shows "The program file
+   * was not found." in the user's language. The player shows the message of
+   * an error thrown from `resolve`; `i18n.error` makes an `Error` whose text
+   * the player translates with this plugin's catalog, while its `message`
+   * stays English for logs and older players.
+   * ```ts
+   * plugin.resolvers.add({
+   *   id: "chip8",
+   *   extensions: ["ch8"],
+   *   async resolve(path, signal) {
+   *     const program = await readFile(path, { signal }).catch(() => {
+   *       // Shown as the open's failure, translated (locales/<lang>.po).
+   *       throw plugin.i18n.error("The program file was not found.");
+   *     });
+   *     return startEmulator(program);
+   *   },
+   * });
+   * ```
    */
   error(source: string, args?: TemplateArgs): TextError;
   /**
@@ -4502,11 +5949,32 @@ interface I18n {
    * @returns The translated string.
    * @throws invalid A malformed value.
    * @capability None.
+   * @example Copy version information in the user's language
+   * "Copy info" puts two translated lines on the clipboard. Text that
+   * leaves the player cannot be translated by it, so `resolve` turns the
+   * values into the string the player would show, using this plugin's
+   * catalog; inside the player, pass the values themselves instead.
+   * ```ts
+   * const { text, list, resolve } = plugin.i18n;
+   * const lines = list([text("Version {}", ["1.0"]), text("Cores: {}", [8])], "lines");
+   * await plugin.clipboard.writeText(resolve(lines));
+   * ```
    */
   resolve(value: TextValue): string;
 }
 ```
 
+Example: Format a date the way the interface language writes it
+
+The OSD shows today's date in the user's language and date format. The
+sentence is a template the player translates; only the data in it, the
+date, is formatted by the plugin, with `i18n.locale` (the language the
+player runs in, fixed for the whole run).
+```ts
+const day = new Date().toLocaleDateString(plugin.i18n.locale);
+await plugin.osd.show("Today is {}", [day]);
+```
+
 ### TextError
 
 An `Error` the player shows translated (I18n.error).
@@ -4532,12 +6000,33 @@ type SettingsCategory = "general" | "playback" | "subtitles" | "video" | "audio"
 
 A page in the player's Options window, made by Settings.page.
 
+A View like a panel: properties and callbacks live on the file's
+bridge global, every callback of the global is forwarded, and there is no
+"bind before show" rule. The page exists from `ready`
+on, whether or not the Options window is open; property writes while it is
+closed are kept and applied when it opens. When pages are added or removed
+while the window is open, the player rebuilds it and restores every page's
+properties to the values last written, so mirror every user change in the
+plugin's state (and `bind` it), or it reverts.
+
+`dispose()`, disposing the scope or stopping the plugin removes the page;
+if it was showing, the window shows another page.
+
+Testing: `host.settingsPage(id)` of `@vestra-player/sdk/testing` has the
+page's `props` and `emit(callback, ...args)`.
+
 - @capability ui.settings
 
 ```ts
 type SettingsPage = View & Disposable & {
   /**
    * Resolves once the player has registered the page; rejects when it refused it.
+   *
+   * The player compiles the page on its own at registration, so a broken
+   * page fails here and does not affect the Options window. Pages added
+   * while `activate` runs must succeed before the plugin is ready: a
+   * rejection fails activation. Later failures also go to
+   * Scope.onError.
    * @throws ui-prepare (rejects) The Slint file does not compile; `message` has the diagnostics.
    * @throws invalid (rejects) The plugin already has 8 pages, or `order` is beyond ±1,000,000.
    * @throws host (rejects) The file is missing or outside the package directory.
@@ -4547,22 +6036,117 @@ type SettingsPage = View & Disposable & {
 };
 ```
 
+Example: Put two preferences on a page and keep them in a store
+
+Options ▸ Video ▸ Blur shows two check boxes whose values survive
+restarts. The checkboxes are bound two-way (`<=>`) to `in-out`
+properties of the bridge global, so the user's clicks show at once; the
+`toggled` callbacks tell the plugin, which saves the new value, and
+`bind` writes the stored values when the page opens.
+```ts
+const store = plugin.storage.json("blur", {
+  defaults: { restoreOnStart: false, messages: true },
+});
+const page = plugin.settings.page("ui/settings.slint", {
+  id: "blur",
+  category: "video",
+  title: "Blur",
+});
+page.bind(() => ({
+  restoreOnStart: store.value.restoreOnStart,
+  messages: store.value.messages,
+}));
+// The bridge's `restore-toggled(bool)` callback, in camelCase.
+page.on("restoreToggled", (on: boolean) =>
+  store.save({ ...store.value, restoreOnStart: on }),
+);
+page.on("messagesToggled", (on: boolean) =>
+  store.save({ ...store.value, messages: on }),
+);
+```
+
+`ui/settings.slint` exports the bridge global and the layout:
+
+```slint
+import { CheckBox } from "std-widgets.slint";
+import { Theme } from "@vestra/theme.slint";
+
+// The bridge: what the plugin writes and the callbacks it handles.
+export global BlurPage {
+    in-out property <bool> restore-on-start;
+    in-out property <bool> messages: true;
+    callback restore-toggled(bool);
+    callback messages-toggled(bool);
+}
+
+export component BlurSettings inherits Rectangle {
+    VerticalLayout {
+        padding: Theme.dialog-padding;
+        spacing: 6px;
+        alignment: start;
+        CheckBox {
+            text: "Turn blur back on when the player starts";
+            checked <=> BlurPage.restore-on-start;
+            toggled => { BlurPage.restore-toggled(self.checked); }
+        }
+        CheckBox {
+            text: "Show on-screen messages";
+            checked <=> BlurPage.messages;
+            toggled => { BlurPage.messages-toggled(self.checked); }
+        }
+    }
+}
+```
+
 ### Settings
 
 Add pages to the player's Options window. `plugin.settings`.
 
+Use a settings page for preferences that change rarely. The player owns
+the Options window (640×480 by default, at least 600×420, resizable): a
+category tree on the left, the selected page on the right, a Close button
+at the bottom. The standard close keys close it, and command key bindings
+do not fire while it has focus. Opening it does not affect playback.
+
+A page file exports **one component and one global**, like a panel: the
+global (the bridge) declares the properties and callbacks, the component
+lays the page out and reads them. Pages are 440 logical pixels wide; the
+window scrolls a taller page.
+
 - @capability ui.settings
 
 ```ts
 interface Settings {
   /**
    * Add a page to the Options window.
+   *
+   * The SDK finds the component and the global from the file's
+   * `export component` and `export global` lines; the file must export one
+   * of each. In the next microtask it registers the page with every property
+   * bound or set so far; `ready` reports the result.
+   *
+   * Within a category, pages are sorted by `order`, then by plugin id and
+   * page id.
    * @capability ui.settings
    * @param file - Path relative to the package directory, for example `"ui/settings.slint"`.
    * @param options - The page's identity and place: `id` (unique in this plugin, 1–64 letters, digits, `.`, `-` or `_`), `category`, `title` (shown in the tree, 1–24 characters) and `order` (an integer within ±1,000,000, default 0; smaller first).
    * @returns A SettingsPage owned by this scope.
    * @throws invalid (throws) A bad `id`, `category`, `title` or `order`, or this plugin already has a page with this `id`.
    * @throws Error without a code (throws) The file does not export exactly one component and one global. A file that cannot be read throws Node's file system error (`code` `ENOENT` and so on).
+   * @example Register a page and report when the player refuses it
+   * An "My plugin" page appears under Plugins, or the reason it could not
+   * be added is logged. `page` returns at once; the player compiles the
+   * page on its own, and `ready` rejects (for example with `ui-prepare`
+   * and the compiler's diagnostics) when it refuses it.
+   * ```ts
+   * const page = plugin.settings.page("ui/advanced.slint", {
+   *   id: "advanced",
+   *   category: "plugins",
+   *   title: "My plugin",
+   *   order: 10, // after pages with a smaller order in the category
+   * });
+   * page.ready.catch((error: PluginError) => console.error(error.message));
+   * ```
    */
   page(file: string, options: {
     /** Unique in this plugin: 1–64 letters, digits, `.`, `-` or `_`. */
@@ -4576,6 +6160,10 @@ interface Settings {
   }): SettingsPage;
   /**
    * Open the Options window at one of this plugin's pages, or bring it to the front.
+   *
+   * Without `pageId` it shows the page that is selected; when the window
+   * first opens, that is the page the user saw last (the player remembers
+   * it), else the first one.
    * @capability ui.settings
    * @param pageId - The `id` of one of this plugin's pages.
    * @returns Resolves once the window is shown.
@@ -4583,16 +6171,48 @@ interface Settings {
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws ui (rejects) The window could not be built (for example a page wrote a property its file does not declare).
    * @throws capability (rejects) The manifest does not declare `ui.settings`.
+   * @example Open the plugin's page from an "Options…" button
+   * The button in the plugin's window opens the Options window at the
+   * plugin's Blur page, or brings it to the front. `show` takes the id the
+   * page was registered with and rejects with `invalid` for any other.
+   * ```ts
+   * const controls = plugin.windows.create("ui/window.slint");
+   * controls.on("openOptions", () => plugin.settings.show("blur"));
+   * ```
    */
   show(pageId?: string): Promise<void>;
 }
 ```
 
+Example: Add a page that edits a stored setting
+
+Options ▸ Playback ▸ Resume shows the plugin's Resume switch. `page`
+registers the page with the Options window (compiled by the player on
+its own), `bind` sends the stored value, and the page's callback saves
+the user's change.
+```ts
+const store = plugin.storage.json("settings", { defaults: { resume: true } });
+const page = plugin.settings.page("ui/settings.slint", {
+  id: "resume",
+  category: "playback",
+  title: "Resume",
+});
+page.bind(() => ({ resume: store.value.resume }));
+// The bridge's `resume-toggled(bool)`: save, and `bind` sends it back.
+page.on("resumeToggled", (on: boolean) => store.save({ ...store.value, resume: on }));
+```
+
 ### BackdropSlot
 
 The backdrop position (`plugin.panels.backdrop`): whether a backdrop is
 mounted and whether it is shown now.
 
+The player decides when the backdrop shows: while the source is empty or
+loading, and while ready media has no video picture (audio files). The
+plugin decides what to draw, from Player.state and
+Player.stats. With `events`, `state` follows every change; without
+it, it refreshes only when this plugin mounts.
+
 - @capability ui.mount; `events` to follow changes.
 
 ```ts
@@ -4607,6 +6227,13 @@ interface BackdropSlot {
    * @capability ui.mount and events
    * @param listener - Receives the new state (`null`: no backdrop).
    * @returns A handle that removes the listener.
+   * @example Log when the backdrop shows or hides
+   * The plugin's log records each change of the backdrop position. The
+   * listener runs when the player starts or stops showing the backdrop
+   * and with `null` when it is unmounted.
+   * ```ts
+   * plugin.panels.backdrop.onChange((state) => console.log("backdrop", state));
+   * ```
    */
   onChange(listener: (state: {
     readonly effective: boolean;
@@ -4614,17 +6241,75 @@ interface BackdropSlot {
 }
 ```
 
+Example: React when a video picture appears
+
+The OSD says "Video is playing" when the backdrop gives way to a video
+picture. The player decides when the backdrop shows (nothing open,
+loading, audio without a picture); `effective` turns false when a video
+frame replaces it.
+```ts
+plugin.panels.backdrop.onChange((state) => {
+  // `null`: no backdrop is mounted.
+  if (state?.effective === false) void plugin.osd.show("Video is playing");
+});
+```
+
 ### Panels
 
 Put a panel into the player's main window: the bottom bar, the sidebar or
 the backdrop. `plugin.panels`.
 
+A panel is part of the player's layout: it resizes with the main window,
+follows fullscreen and auto-hides with the player's own controls. Use one
+for content that should stay with the video (a playlist, chapters, a
+custom control bar, cover art); use a tool window for a
+tool the user opens and closes.
+
+A panel file exports **one component and one global**. The global is the
+bridge: the plugin writes its properties and handles its callbacks. The
+component lays the panel out and reads and calls the global. The split
+exists because the player composes the component into its own windows: a
+new instance of the component is made whenever the main window is rebuilt
+or the sidebar moves to or from its floating window, while the global is
+one stable address.
+
+Each plugin mounts at most one panel, and each position holds one panel
+for all plugins. Panels.bottom and Panels.sidebar describe
+the positions, whoever mounted there.
+
 - @capability ui.mount
 
 ```ts
 interface Panels {
   /**
    * Mount a Slint component in the bottom bar, the sidebar or the backdrop.
+   *
+   * Returns at once; the panel is on screen when Panel.ready
+   * resolves. Handlers and bindings made right after `mount()` (in the same
+   * synchronous code) are part of the first values.
+   *
+   * - `"bottom"`: under the video, as wide as the video column, as tall as the
+   *   component's preferred height. It may draw above its slot into the video
+   *   area (negative `y`); the player does not clip it. In fullscreen it
+   *   floats over the video and shows only while the pointer is in its band
+   *   at the bottom of the screen (hidden 500 ms after the pointer leaves;
+   *   Panel.setInteraction locks keep it).
+   * - `"sidebar"`: right of the video, the window's full height, as wide as the
+   *   user drags it (at least 317). The user can detach it into a floating
+   *   window titled `title`. Several plugins may mount here (player 0.4.x
+   *   after 0.4.0): each panel is a tab, labelled `title` (else the plugin's
+   *   name), and the player draws a 31px tab strip above the current one
+   *   while there are two or more (with one panel, nothing changes).
+   *   Showing, hiding and detaching apply to the whole sidebar. If the
+   *   bridge global declares `in property <bool> tabbed`, the player sets
+   *   it to `true` while it draws the strip, so a panel with a tab strip of
+   *   its own can hide it. Panel coordinates (drops) start below the strip.
+   * - `"backdrop"`: the whole video area, under the OSD, while there is no
+   *   video picture (see Panels.backdrop). One plugin at a time (as
+   *   for the bottom bar, another one's mount rejects with `conflict`); it
+   *   takes no pointer or keyboard input. While it is mounted, the player does
+   *   not show the cover art of audio files itself (from the next file
+   *   opened on), so the plugin can draw it.
    * @capability ui.mount
    * @param slot - Where to mount the panel.
    * @param file - Path relative to the package directory, for example `"ui/playlist.slint"`.
@@ -4632,6 +6317,19 @@ interface Panels {
    * @returns A Panel owned by this scope; await Panel.ready for the result.
    * @throws Error without a code (throws) This plugin already has a panel, or the file exports no component or global, or several and `options` does not name one. A file that cannot be read throws Node's file system error (`code` `ENOENT` and so on).
    * @throws The errors of Panel.ready (rejects `ready`) The player refused the mount.
+   * @example Mount a bottom bar with a seek slider
+   * The plugin's own control bar appears under the video, its slider
+   * following the playback position and seeking when dragged. Bindings and
+   * handlers made right after `mount` are part of the first values;
+   * `ready` resolves once the main window shows the bar, and rejects with
+   * `conflict` when another plugin's panel holds the bottom bar.
+   * ```ts
+   * const bar = plugin.panels.mount("bottom", "ui/bar.slint");
+   * // Sent again whenever the position changes.
+   * bar.bind(() => ({ position: plugin.player.state.position ?? 0 }));
+   * bar.on("seek", (seconds: number) => plugin.player.seek(seconds));
+   * await bar.ready;
+   * ```
    */
   mount(slot: "bottom" | "sidebar" | "backdrop", file: string, options?: {
     /** The exported component to mount, if the file exports several. */
@@ -4650,6 +6348,67 @@ interface Panels {
 }
 ```
 
+Example: Mount a list in the sidebar (examples/panel-menu)
+
+The sidebar gets an "Example list" tab showing three rows. `mount`
+returns at once; the SDK sends the mount with the values bound so far,
+and the player rebuilds its main window with the panel. The Slint file
+exports the component and the bridge global whose properties `bind`
+writes.
+
+```ts
+const panel = plugin.panels.mount("sidebar", "ui/panel.slint", {
+  title: "Example list",
+});
+// Sent when the panel mounts, then whenever a value changes.
+panel.bind(() => ({ rows: items, selected }));
+```
+
+`ui/panel.slint`:
+
+```slint
+import { Theme } from "@vestra/theme.slint";
+
+export global ListBridge {
+    in property <[string]> rows;
+    in property <int> selected;
+    callback select(int);
+    callback context-menu(float, float);
+}
+
+export component ListPanel inherits Rectangle {
+    background: Theme.bg-list;
+    min-width: 200px;
+    VerticalLayout {
+        for row[index] in ListBridge.rows: Rectangle {
+            height: 20px;
+            background: index == ListBridge.selected ? Theme.selected-bg : transparent;
+            Text {
+                x: 6px;
+                text: (index + 1) + ". " + row;
+                color: index == ListBridge.selected ? Theme.text : Theme.text-list;
+                font-size: Theme.font-body;
+                vertical-alignment: center;
+            }
+            TouchArea {
+                pointer-event(event) => {
+                    if event.kind == PointerEventKind.down {
+                        ListBridge.select(index);
+                    }
+                    if event.kind == PointerEventKind.up && event.button == PointerEventButton.right {
+                        ListBridge.context-menu((self.absolute-position.x + self.mouse-x) / 1px,
+                            (self.absolute-position.y + self.mouse-y) / 1px);
+                    }
+                }
+            }
+        }
+        // Takes the space below the rows. Without it the layout's maximum
+        // height (three 20px rows) would cap the player's main window.
+        Rectangle { vertical-stretch: 1; }
+    }
+}
+```
+
 ### MarkKind
 
 What a timeline mark stands for; readers choose colours by it.
@@ -4683,6 +6442,19 @@ This plugin's own marks; disposing it removes them.
 interface TimelineLayer extends Disposable {
   /**
    * Replace the layer (last write wins; `[]` clears it). At most 1000 marks, titles ≤ 100 characters, times within the media. Failures go to `onError`; with `ifCurrent`, a write for another source is dropped silently. A title is data (a chapter's or bookmark's own name), or a Text the player translates (`text("Chapter {}", [n])`, SDK 1.5.11); other plugins read the shown string.
+   * @example Show the file's bookmarks on the timeline
+   * Bookmark marks appear on the seek bar at their times, titled with the
+   * user's notes. `set` replaces this plugin's whole layer; with `ifCurrent`
+   * the player drops the write if another file opened since `seen` was
+   * read, so bookmarks of the previous file never land on the new one.
+   * ```ts
+   * const layer = plugin.timeline.layer();
+   * const seen = plugin.player.state; // the file the bookmarks belong to
+   * layer.set(
+   *   bookmarks.map((b) => ({ time: b.time, kind: "bookmark", title: b.note })),
+   *   { ifCurrent: seen },
+   * );
+   * ```
    */
   set(marks: {
     time: number;
@@ -4791,11 +6563,42 @@ interface MainWindow {
    *
    * Where it is unsupported (Windows, Linux), `setVideoArea` plus
    * `setAlwaysOnTop` make a reasonable "mini player" fallback.
+   * @example Toggle picture-in-picture where the system has it
+   * The video moves into a floating picture-in-picture window, or back.
+   * `state.pictureInPicture` says whether the system supports it and
+   * whether it is on; the plugin only calls `setPictureInPicture` where it
+   * is supported.
+   * ```ts
+   * if (plugin.window.state.pictureInPicture.supported)
+   *   await plugin.window.setPictureInPicture(!plugin.window.state.pictureInPicture.active);
+   * ```
    */
   setPictureInPicture(on: boolean): Promise<void>;
 }
 ```
 
+Example: Resize the window to the video's own size
+
+Screen ▸ Original size makes the video area as many logical points as
+the video has pixels (one pixel per pixel at a display scale of 100 %).
+`stats()` reports the video's size;
+`setVideoArea` resizes the window around the video column (bars and a
+docked sidebar added), scales it down if it would not fit the screen,
+and is refused in fullscreen, hence the `enabled` check.
+```ts
+plugin.commands.add({
+  id: "size-1x",
+  path: ["Screen", "Original size"],
+  enabled: () => !plugin.window.state.fullscreen,
+  run: async () => {
+    const stats = await plugin.player.stats();
+    // No video stream (an audio file): nothing to size to.
+    if (stats.video?.width && stats.video.height)
+      await plugin.window.setVideoArea({ width: stats.video.width, height: stats.video.height });
+  },
+});
+```
+
 ### AppInfo
 
 `plugin.app`: fixed for the life of the plugin process.
@@ -4830,6 +6633,18 @@ interface App extends AppInfo {
 }
 ```
 
+Example: Describe the player and the system for a bug report
+
+The plugin builds a line such as "Vestra 0.5.10 on macOS 26.2" to copy
+into a bug report. `app.version` is known from the start; each
+`system()` call asks the player, which reads the displays at that moment.
+The operating system's name and version it works out once, at the first
+call, and reuses them.
+```ts
+const system = await plugin.app.system();
+const text = `Vestra ${plugin.app.version} on ${system.name} ${system.version ?? ""}`;
+```
+
 ### SystemInfo
 
 What App.system reports.
@@ -4905,12 +6720,37 @@ interface ConfirmOptions {
 The system's own dialogs: a confirmation alert and the open and save file
 dialogs. `plugin.dialogs`.
 
+The plugin passes text and gets the answer; the system draws the dialog,
+so it looks and behaves like every other dialog on the system. Each call
+resolves when the user answers; there is no time limit and no way to close
+a dialog from code. Only one dialog (of any kind, from any plugin) is open
+at a time: another call meanwhile rejects with `busy`. Playback continues
+while a dialog is open; command key bindings pause.
+
+**Platforms:** Dialogs.confirm needs macOS or Windows (other
+systems reject it with `unsupported`); the file dialogs work on every
+system.
+
+For anything more than a question or a path, use a tool
+window.
+
 - @capability ui.dialog
 
 ```ts
 interface Dialogs {
   /**
    * Ask the user to confirm something, in a system alert.
+   *
+   * **macOS:** an `NSAlert` sheet on the active player window (usually the
+   * tool window the user just clicked in), else on the main window.
+   *
+   * **Windows:** a task dialog owned by the active player window, titled
+   * "Vestra Player"; `detail` follows `message` after a blank line. A
+   * `checkbox` is asked as a second yes/no dialog after the user confirms
+   * (on cancel it is not asked and `checked` is `false`).
+   *
+   * Remembering "Don't ask again" is up to the plugin (see
+   * Scope.storage).
    * @capability ui.dialog
    * @param options - The text and buttons; see ConfirmOptions.
    * @returns The answer: `confirmed` is `true` when the user picked the confirm button (Escape, the cancel button or closing the dialog give `false`); `checked` is the checkbox's state (`false` without one).
@@ -4919,6 +6759,23 @@ interface Dialogs {
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws unsupported (rejects) A system other than macOS and Windows.
    * @throws capability (rejects) The manifest does not declare `ui.dialog`.
+   * @example Confirm before replacing the playlist
+   * The user sees "Replace the current playlist?" with a Replace button and
+   * the playlist is replaced only after a yes. The system draws the alert
+   * and the promise resolves when the user answers; only one dialog is
+   * open at a time, so a second one meanwhile rejects with `busy`.
+   * ```ts
+   * try {
+   *   const { confirmed } = await plugin.dialogs.confirm({
+   *     message: "Replace the current playlist?",
+   *     confirm: "Replace",
+   *   });
+   *   if (confirmed) await plugin.osd.show("Playlist replaced");
+   * } catch (error) {
+   *   if ((error as PluginError).code !== "busy") throw error;
+   *   // Another dialog is already open: let the user finish that one.
+   * }
+   * ```
    */
   confirm(options: ConfirmOptions): Promise<{
     /** The user picked the confirm button. */
@@ -4935,6 +6792,14 @@ interface Dialogs {
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws invalid (rejects) `title` is longer than 256 bytes.
    * @throws capability (rejects) The manifest does not declare `ui.dialog`.
+   * @example Let the user pick a subtitle file
+   * The system's Open dialog appears titled "Choose a subtitle file" and
+   * the chosen path is shown on the OSD. The promise resolves when the
+   * user answers: with the absolute path, or `null` when they cancelled.
+   * ```ts
+   * const path = await plugin.dialogs.openFile({ title: "Choose a subtitle file" });
+   * if (path !== null) await plugin.osd.show("Chosen: {}", [path]); // a path is data
+   * ```
    */
   openFile(options?: {
     /** The dialog's title (English source text or a Text), at most 256 bytes. */
@@ -4949,6 +6814,14 @@ interface Dialogs {
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws invalid (rejects) `title` is longer than 256 bytes.
    * @throws capability (rejects) The manifest does not declare `ui.dialog`.
+   * @example Let the user pick several files at once
+   * The Open dialog allows selecting several files; the OSD says how many
+   * were added. The promise resolves with the absolute paths, or with an
+   * empty array when the user cancelled.
+   * ```ts
+   * const paths = await plugin.dialogs.openFiles({ title: "Add to the playlist" });
+   * if (paths.length) await plugin.osd.show("{} files added", [paths.length]);
+   * ```
    */
   openFiles(options?: {
     /** The dialog's title (English source text or a Text), at most 256 bytes. */
@@ -4963,6 +6836,14 @@ interface Dialogs {
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws invalid (rejects) `title` is longer than 256 bytes.
    * @throws capability (rejects) The manifest does not declare `ui.dialog`.
+   * @example Let the user choose a folder for snapshots
+   * The system's folder dialog appears titled "Save snapshots in". It
+   * resolves with the folder's absolute path, or `null` when the user
+   * cancelled, in which case the plugin stops there.
+   * ```ts
+   * const folder = await plugin.dialogs.openDirectory({ title: "Save snapshots in" });
+   * if (folder === null) return; // cancelled
+   * ```
    */
   openDirectory(options?: {
     /** The dialog's title (English source text or a Text), at most 256 bytes. */
@@ -4970,6 +6851,8 @@ interface Dialogs {
   }): Promise<string | null>;
   /**
    * Ask the user where to save a file.
+   *
+   * The dialog only returns a path; writing the file is up to the plugin.
    * @capability ui.dialog
    * @param options - `title`: the dialog's title, at most 256 bytes. `fileName`: the proposed file name (a plain name without `/` or `\`, at most 256 bytes).
    * @returns The absolute path, or `null` when the user cancelled.
@@ -4977,6 +6860,14 @@ interface Dialogs {
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws invalid (rejects) `title` is too long, or `fileName` is too long or contains `/` or `\`.
    * @throws capability (rejects) The manifest does not declare `ui.dialog`.
+   * @example Ask where to save a snapshot
+   * The system's Save dialog proposes "frame.png" and returns where the
+   * user wants it. The dialog only returns the path (or `null` when
+   * cancelled); writing the file is up to the plugin afterwards.
+   * ```ts
+   * const path = await plugin.dialogs.saveFile({ title: "Save snapshot", fileName: "frame.png" });
+   * if (path === null) return; // cancelled
+   * ```
    */
   saveFile(options?: {
     /** The dialog's title (English source text or a Text), at most 256 bytes. */
@@ -4989,6 +6880,32 @@ interface Dialogs {
 }
 ```
 
+Example: Ask before deleting, remembering "Don't ask again"
+
+Deleting asks for confirmation in a system alert with a "Don't ask
+again" box; once the user ticks it, later deletes go ahead without
+asking. `confirm` resolves with the button and the checkbox when the
+user answers; the texts are templates the player translates, so the
+count goes in `args`. Remembering the box is up to the plugin.
+```ts
+const store = plugin.storage.json("confirm", { defaults: { askBeforeDelete: true } });
+async function deleteAll(count: number) {
+  if (store.value.askBeforeDelete) {
+    const { confirmed, checked } = await plugin.dialogs.confirm({
+      message: "Delete {} bookmarks?",
+      args: [count],
+      detail: "This cannot be undone.",
+      confirm: "Delete",
+      destructive: true,
+      checkbox: "Don't ask again",
+    });
+    if (!confirmed) return;
+    if (checked) store.save({ askBeforeDelete: false });
+  }
+  // … delete …
+}
+```
+
 ### AudioTrack
 
 One audio track of the current media (PlayerState.audioTracks).
@@ -5133,6 +7050,23 @@ interface Conditional {
 }
 ```
 
+Example: Play the next file only if nothing else was opened
+
+When the plugin's file ends, the next one starts, unless the user or
+another plugin opened something in the meantime. `onEnd` passes the
+state at the end; `open` with `ifCurrent: ended` is refused with `stale`
+when the source changed after that state, so nothing is replaced.
+```ts
+media.onEnd(async (ended) => {
+  try {
+    await plugin.player.open(next, { ifCurrent: ended });
+  } catch (error) {
+    // Someone opened another file: leave it playing.
+    if ((error as PluginError).code !== "stale") throw error;
+  }
+});
+```
+
 ### Media
 
 A source this plugin opened.
@@ -5179,6 +7113,15 @@ interface Scrub {
    * the target of a keyframe seek is always sent. Omitted or `false`: exact,
    * as before. Older players ignore the option and seek exactly: set
    * `"minPlayerVersion": "0.5.3"` when you rely on it.
+   * @example Scrub on keyframes for a fast picture
+   * While dragging, the picture jumps to the nearest earlier keyframe at
+   * once instead of decoding up to the exact frame. With `keyframes: true`
+   * the player lands each target on the last keyframe at or before it; the
+   * plugin follows the user's keyframe-seek setting.
+   * ```ts
+   * const keyframes = true; // the plugin's own setting
+   * bar.on("dragMove", (seconds: number) => void scrub?.seek(seconds, { keyframes }));
+   * ```
    */
   seek(seconds: number, options?: {
     keyframes?: boolean;
@@ -5190,6 +7133,21 @@ interface Scrub {
 }
 ```
 
+Example: Seek while the user drags a slider
+
+The video follows the slider while it is dragged. `scrub()` starts a
+gesture from the current state; each `seek` is conditional on the
+previous one and only the newest target is sent while one is running,
+so a fast drag does not queue seeks. A change from outside (another file,
+the user pausing) ends the gesture and later seeks resolve `false`.
+```ts
+let scrub: Scrub | null = null;
+bar.on("dragStart", () => (scrub = plugin.player.scrub()));
+// Latest value wins: superseded targets resolve false, not an error.
+bar.on("dragMove", (seconds: number) => void scrub?.seek(seconds));
+bar.on("dragEnd", () => scrub?.end());
+```
+
 ### StreamFrame
 
 Frames a stream supplies on demand: RGBA pixels and 48 kHz stereo f32 PCM.
@@ -5414,6 +7372,24 @@ interface Player {
    * TCP with a token on Windows. Rejects with a StreamStartError
    * (`timeout`), `stream`, `device`, or `replaced` when another source
    * replaced it (or it was closed) before it ran.
+   * @example Play pictures the plugin draws itself
+   * The player shows a 320×240 picture the plugin renders, with silence as
+   * its sound, as the current source. The SDK pulls frames on the audio
+   * clock: each `frame()` returns one picture (RGBA bytes) and the audio
+   * that plays with it, here 1/60 s, so the picture runs at 60 frames a
+   * second; `frame()` may run several times back to back to refill the
+   * lead. `onStop` tells the plugin when and why the stream ended.
+   * ```ts
+   * const frame = new Uint8Array(320 * 240 * 4); // RGBA, reused per frame
+   * const silence = new Float32Array(2 * 800); // 1/60 s of stereo at 48 kHz
+   * const stream = await plugin.player.openStream({
+   *   width: 320,
+   *   height: 240,
+   *   frame: () => ({ video: render(frame), audio: silence }),
+   * });
+   * // `error` is null when the stream stopped normally.
+   * stream.onStop((error) => error && plugin.osd.show(error.message));
+   * ```
    */
   openStream(options: StreamOptions): Promise<Stream>;
   /** Pause or resume. */
@@ -5433,7 +7409,28 @@ interface Player {
     volume?: number;
     muted?: boolean;
   }): Promise<boolean>;
-  /** Become the sequence provider (one at a time; another provider rejects with `conflict` through the scope's `onError`, or fails activation). Dispose to stop. */
+  /**
+   * Become the sequence provider (one at a time; another provider rejects with `conflict` through the scope's `onError`, or fails activation). Dispose to stop.
+   * @example Drive the player's Next and Previous from a playlist
+   * The player's Next and Previous items and keys play the plugin's list.
+   * The player calls `next` and `previous` when the user asks; `canNext`
+   * and `canPrevious` are evaluated again after every handler the SDK runs,
+   * and while they return false the player disables its items ("No next
+   * item").
+   * ```ts
+   * const playAt = async (at: number) => {
+   *   index = at;
+   *   await plugin.player.open(items[at]!);
+   * };
+   * // Called by the player's Next / Previous items, keys and buttons.
+   * plugin.player.provideSequence({
+   *   next: () => playAt(index + 1),
+   *   previous: () => playAt(index - 1),
+   *   canNext: () => index + 1 < items.length,
+   *   canPrevious: () => index > 0,
+   * });
+   * ```
+   */
   provideSequence(provider: SequenceProvider): Disposable;
   /** Ask the provider to go forward / back. Rejects `unavailable` when it cannot. */
   next(): Promise<void>;
@@ -5514,6 +7511,22 @@ interface Player {
 }
 ```
 
+Example: Open a file and wait until it plays
+
+The file opens and the plugin learns whether it started playing within
+ten seconds. `open` resolves once the player accepted the load and
+returns a `Media` handle; `ready` waits for playback and rejects with
+`failed` (load error), `replaced` (another source took over) or an
+`AbortError` when the timeout fires, which closes the media.
+```ts
+const media = await plugin.player.open("/Movies/clip.mp4"); // load accepted
+try {
+  await media.ready({ signal: AbortSignal.timeout(10_000) });
+} catch (error) {
+  void plugin.osd.show("Cannot play: {}", [(error as Error).message]);
+}
+```
+
 ### HostAction
 
 The core's basic playback actions (menu commands owned by the player),
@@ -5554,6 +7567,21 @@ interface Host {
    * `invalid` for an unknown id. Needs `commands`.
    *
    * Prefer this over reimplementing playback buttons.
+   * @example Make a bar button play and pause like Space
+   * The plugin's own Play button behaves exactly like the player's Space
+   * key, including its on-screen text. `host.run` runs the core action
+   * with the player's checks; it resolves when the action finished, and
+   * rejects with `unavailable` while the action is disabled (nothing open).
+   * ```ts
+   * bar.on("playPause", async () => {
+   *   try {
+   *     await plugin.host.run("play-pause");
+   *   } catch (error) {
+   *     if ((error as PluginError).code !== "unavailable") throw error;
+   *     // Nothing to play: the button simply does nothing.
+   *   }
+   * });
+   * ```
    */
   run(action: HostAction): Promise<void>;
   /**
@@ -5569,6 +7597,14 @@ interface Host {
    * once the seek is submitted, as before. `invalid` for `seconds` out of
    * range.
    * @player 0.5.1 (set `"minPlayerVersion": "0.5.1"`: older players ignore `seconds` and seek by the `setStepSeek` step)
+   * @example Add a 30-second skip that adds up with the arrow keys
+   * The plugin's "+30 s" button seeks forward 30 seconds and shows the same
+   * text as →. Passing `seconds` makes the core step seek use that step
+   * with the player's mode (exact or keyframes); quick presses of it and of
+   * → add up into one seek.
+   * ```ts
+   * bar.on("forward30", () => plugin.host.run("seek-forward", { seconds: 30 }));
+   * ```
    */
   run(action: "seek-backward" | "seek-forward", options: {
     seconds: number;
@@ -5582,21 +7618,55 @@ This plugin's information block on the OSD: multi-line text over the
 video that stays until the plugin changes or removes it. Made by
 Osd.panel.
 
+The block sits under the OSD message line, on a translucent dark plate
+(see Osd for sizes), and takes no input. When
+several plugins have one, they are stacked from top to bottom. `dispose()`,
+disposing the scope or stopping the plugin removes it.
+
 - @capability ui.osd
 
 ```ts
 interface OsdPanel extends Disposable {
   /**
    * Show the block with this text, change it, or hide it.
+   *
+   * Latest value wins: calling it on every state change is fine, the same
+   * text is not sent twice and only the newest text is sent while a write is
+   * in flight. Never throws; a failed write goes to Scope.onError
+   * (`invalid` for too much text, `unavailable` without a user interface,
+   * `capability` without `ui.osd`).
    * @capability ui.osd
    * @param text - The text, with `\n` between lines: at most 32 lines and 4096 bytes once translated and formatted. `null` hides the block. A template, like Osd.show's.
    * @param args - Values for its placeholders (player 0.4.3); `null` or omitted for none.
    * @param options - `maxColumns`: cut long lines (SDK 1.5.11).
+   * @example Show two loop points, then hide the block
+   * The block shows "A: 12.0 s" and "B: 18.5 s" on two lines, then
+   * disappears. The text is a template the player translates and fills
+   * in; `\n` separates lines, and `null` hides the block.
+   * ```ts
+   * const info = plugin.osd.panel();
+   * info.set("A: {} s\nB: {} s", ["12.0", "18.5"]);
+   * info.set(null); // hide it
+   * ```
    */
   set(text: TextValue | null, args?: TemplateArgs | null, options?: OsdPanelOptions): void;
 }
 ```
 
+Example: Show live playback numbers over the video
+
+A block over the video shows the position and the duration, updated
+as playback moves. `player.onChange` runs after the SDK updated the
+state (with `events`); `set` never throws and sends only the newest
+text while one is in flight, so calling it on every change is fine.
+```ts
+const info = plugin.osd.panel();
+plugin.player.onChange((state) =>
+  // A template with data arguments; the player translates "{} / {} s".
+  info.set("{} / {} s", [state.position?.toFixed(1) ?? "–", state.duration?.toFixed(1) ?? "–"]),
+);
+```
+
 ### OsdPanelOptions
 
 Options of OsdPanel.set.
@@ -5615,12 +7685,50 @@ interface OsdPanelOptions {
 Text the player draws over the video: short messages and an information
 block. `plugin.osd`.
 
+The on-screen display (OSD) is the lightest way to tell the user something:
+no Slint file, no window, visible in fullscreen. A message
+(Osd.show) is one line at the top left of the video that
+disappears after 2 seconds; a newer message, from any plugin, replaces it.
+The information block (Osd.panel) stays until the plugin changes
+or removes it.
+
+How the player draws them (a player before 0.4.0 drew bold white text
+with a black outline instead):
+
+- **Message**: white text on a translucent dark plate with rounded
+  corners and a gradient line along its bottom edge, 10px from the
+  video area's left and top edges.
+- **Font size** follows the video area: 3 % of its height, rounded and
+  clamped to 12–48px (about 18px in the default window, 32px in
+  fullscreen at 1080 pixels high). The plate's padding and corners scale
+  with it.
+- **Information block**: 4px below the message plate, on the same kind of
+  plate; its font scales in proportion (11px when the message is 16px),
+  clamped to 9–28px.
+
+How long a text may be is in
+Limits: on-screen display
+(OSD_LIMITS).
+
 - @capability ui.osd
 
 ```ts
 interface Osd {
   /**
    * Show a one-line message at the top left of the video for 2 seconds.
+   *
+   * Replaces the message on screen, whichever plugin showed it. A message
+   * that is on screen when the plugin stops still disappears on time.
+   *
+   * The text is a template in English: the player shows its translation
+   * from the plugin's catalog, with the placeholders (`{}`, `{0}`, `{name}`;
+   * `{{` and `}}` for braces) filled from `args`. Without `args` the text
+   * shows as it is (braces included). Untranslated, the English template is
+   * formatted. Never compose the sentence in TypeScript
+   * (`` `Speed ${rate}×` ``): translators can only translate whole templates.
+   * An argument that is itself words is a Text (SDK 1.5.11), and a
+   * message made of a varying number of parts is a TextList of
+   * texts; `text` may also be a `Text` (then without `args`).
    * @capability ui.osd
    * @param text - The template, 1–200 characters once translated and formatted; line breaks become spaces.
    * @param args - Values for its placeholders (player 0.4.3; older players show the template as it is).
@@ -5628,18 +7736,51 @@ interface Osd {
    * @throws invalid (rejects) The shown text is empty, only white space, or longer than 200 characters, or `args` is not a TemplateArgs.
    * @throws unavailable (rejects) The player runs without a user interface.
    * @throws capability (rejects) The manifest does not declare `ui.osd`.
+   * @example Confirm an action and show a value
+   * The OSD shows "Bookmark added", then "Speed 1.5×" in the user's
+   * language. The text is English source the player translates with the
+   * plugin's catalog; `{}` is filled in with the argument, which stays as
+   * it is because it is data.
+   * ```ts
+   * await plugin.osd.show("Bookmark added");
+   * await plugin.osd.show("Speed {}×", [plugin.player.state.rate]);
+   * ```
    */
   show(text: TextValue, args?: TemplateArgs): Promise<void>;
   /**
    * Create this plugin's information block.
+   *
+   * Nothing is shown until OsdPanel.set. A plugin has one block;
+   * dispose it before creating another.
    * @capability ui.osd
    * @returns An OsdPanel owned by this scope.
    * @throws Error without a code (throws) This plugin already has a block.
+   * @example Show a status block over the video
+   * A small block over the video says "Loop: off" until the plugin changes
+   * or hides it. Each plugin has one block, stacked with other plugins'
+   * blocks; a second `panel()` call throws.
+   * ```ts
+   * const info = plugin.osd.panel();
+   * info.set("Loop: off");
+   * ```
    */
   panel(): OsdPanel;
 }
 ```
 
+Example: Show on-screen messages the user can turn off
+
+"Blur on" appears over the video unless the user turned messages off in
+the plugin's settings. `osd.show` asks the player to draw the text for a
+moment; the plugin checks its own stored preference before each call.
+```ts
+const store = plugin.storage.json("prefs", { defaults: { messages: true } });
+const say = (text: string) => {
+  if (store.value.messages) void plugin.osd.show(text);
+};
+say("Blur on");
+```
+
 ### FilterStatus
 
 The state of a filter, display layer or render options handle.
@@ -5698,6 +7839,19 @@ same chain applies to processed snapshots and exports.
 type VideoFilter = Filter<VideoNode[]>;
 ```
 
+Example: Brighten the picture and report when it fails
+
+Every video plays a little brighter with more contrast, and the OSD
+says why when the player cannot apply it. `set` records the desired
+chain (last write wins, one request in flight); the player reapplies it
+for each new source, and `onStatus` reports `applied` or `failed`.
+```ts
+const picture = plugin.video.filter("picture");
+// `unsupported` while a generated stream plays: its frames skip filters.
+picture.onStatus((s) => s.state === "failed" && plugin.osd.show(s.error.message));
+picture.set([{ kind: "eq", brightness: 0.1, contrast: 1.1, saturation: 1, gamma: 1 }]);
+```
+
 ### AudioFilter
 
 This plugin's own audio chain plus its audio delay in 10 ms steps.
@@ -5717,6 +7871,16 @@ type AudioFilter = Filter<{
 }>;
 ```
 
+Example: Lower the volume and delay the sound
+
+Every file plays 6 dB quieter, with its sound 120 ms later to match a
+slow display. `set` sends the plugin's whole chain and delay; the
+player applies it to each source and adds the delays of all plugins.
+```ts
+const audio = plugin.audio.filter("sound");
+audio.set({ nodes: [{ kind: "volume", gainDb: -6 }], delayMs: 120 }); // 10 ms steps
+```
+
 ### ViewSettings
 
 How the video sits in the video area; not part of snapshots or exports.
@@ -5759,6 +7923,18 @@ interface VideoView extends Disposable {
 }
 ```
 
+Example: Fill the window, then zoom in
+
+The video fills the video area (cropped instead of letterboxed), then
+zooms to 150 % shifted a little to the right. The first plugin to call
+`view()` owns the display layer; each `set` merges into its settings,
+which stay across sources until the plugin resets them or stops.
+```ts
+const view = plugin.video.view();
+view.set({ fit: "fill" });
+view.set({ zoom: 1.5, panX: 0.1 }); // merged with the previous write
+```
+
 ### RenderSettings
 
 GPU renderer options; not part of snapshots or exports.
@@ -5801,6 +7977,21 @@ interface RenderOptions extends Disposable {
 }
 ```
 
+Example: Tone-map HDR video and hide the menu where it cannot work
+
+On a GPU-rendering player HDR video is tone-mapped with BT.2390 for a
+250-nit display; under software rendering the plugin hides its HDR menu.
+`set` merges the values into the plugin's render options and the
+player reports the result through `onStatus`: `failed` with
+`unsupported` means the player renders in software (Windows, Linux).
+```ts
+const render = plugin.video.render();
+render.onStatus((s) => {
+  if (s.state === "failed" && s.error.code === "unsupported") hideHdrMenu();
+});
+render.set({ toneMapping: "bt.2390", targetPeak: 250 }); // nits
+```
+
 ### SubtitleTrack
 
 A subtitle track of the current source.
@@ -5855,7 +8046,7 @@ interface SubtitlesState {
     /** Font family name for display. */
     family: string;
   }[];
-  /** The effective style, from whichever plugin set it last. */
+  /** The effective style: among the plugins that set a layer, the one whose manifest id sorts last (not the most recent call); `null` without one. */
   readonly style: SubtitleStyle | null;
   /** Whether the renderer confirmed the selection. */
   readonly trackConfirmation: "waiting" | "applied" | "uncertain";
@@ -5918,11 +8109,36 @@ interface Subtitles {
   }): Promise<SubtitleTrack>;
   /** Remove a track this plugin loaded. */
   remove(track: SubtitleTrack, options?: SubtitleConditional): Promise<SubtitlesState>;
-  /** This plugin's style layer; `null` removes it. Last write wins. */
+  /**
+   * Set this plugin's style layer; `null` removes it. The newest call of this plugin replaces its earlier layer. When several plugins have a layer, the player uses the one whose manifest id sorts last, whatever the order of the calls.
+   */
   setStyle(style: SubtitleStyle | null, options?: SubtitleConditional): Promise<SubtitlesState>;
 }
 ```
 
+Example: Load an SRT file as the secondary subtitle
+
+An English SRT file shows as a second subtitle line next to the
+film's own subtitles, in white with an outline. The plugin reads the
+file and uploads its bytes with `load`, which adds a track to the
+current source and selects it as the secondary subtitle; `refresh`
+reads the subtitle state for its font list, and `setStyle` sends this
+plugin's style layer naming one of those fonts.
+```ts
+const bytes = await readFile(path);
+await plugin.subtitles.load(bytes, { title: "English", select: "secondary" });
+const { fonts } = await plugin.subtitles.refresh();
+if (!fonts.length) return;
+await plugin.subtitles.setStyle({
+  fontId: fonts[0]!.id,
+  fontSize: 40, // at the 1080p reference height
+  color: "white",
+  outline: 2,
+  marginPercent: 5,
+  offsetMs: 0,
+});
+```
+
 ### CaptureOptions
 
 Options of MediaCapture.capture. Conditional on `player.state`
@@ -6053,6 +8269,28 @@ interface MediaCapture {
 }
 ```
 
+Example: Save the current frame as JPEG
+
+The frame on screen, with the plugin's own picture effects, is saved
+where the user chooses. `capture` freezes the source as it was in
+`seen` (and fails with `stale` if the user opened another file while
+the dialog was open); `export` decodes offline without disturbing
+playback, and `done` resolves with the job's final status.
+```ts
+const seen = plugin.player.state;
+const destination = await plugin.dialogs.saveFile({ fileName: "frame.jpg" });
+if (!destination) return;
+const snapshot = await plugin.media.capture({ ifCurrent: seen, processed: true });
+// Release the frozen frame whatever happens to the export.
+try {
+  const job = await snapshot.export({ format: "jpeg", destination, quality: 85 });
+  const end = await job.done;
+  if (end.status !== "completed") throw new Error(`export ${end.status}`);
+} finally {
+  await snapshot.dispose();
+}
+```
+
 ### ResolverOptions
 
 Declaration of Resolvers.add: a web resolver
@@ -6087,6 +8325,24 @@ playlist, next / previous, the recent list, a drop that calls `open`),
 the player asks this plugin for a stream it generates instead of
 playing the file. Needs `source.resolve` and `producer.av`.
 
+The open keeps everything of the original call: its `ifCurrent`, its
+operation (the opener's `open` and `media.ready()` settle as for any
+file), `paused` (the stream starts paused), and its path as
+`state.source`, with `state.kind` `"stream"`. A thrown error fails that
+open: `phase` `"error"` with the error's message as `state.error`,
+word for word. The stream belongs to this plugin, as with
+Player.openStream.
+
+Cancellation: `signal` aborts when the open is replaced, closed
+(`player.close()`, F4) or times out (30 seconds), or this resolver is
+disposed. Cancelled after `resolve` returned but before the stream ran,
+the SDK releases the stream and never calls `started`.
+
+One extension has one resolver: another plugin's resolver for it makes
+Resolver.ready reject with `conflict` without failing activation
+(the player shows a warning). When this plugin stops, its extensions are
+free again and such files go to the player as before.
+
 ```ts
 interface FileResolverOptions {
   /** Local id, unique within the plugin. */
@@ -6100,6 +8356,32 @@ interface FileResolverOptions {
 }
 ```
 
+Example: Play CHIP-8 programs with the plugin's own emulator
+
+Opening a `.ch8` file anywhere in the player (Open dialog, playlist,
+recent list) runs it in the plugin's emulator instead of failing as an
+unknown format. The player calls `resolve` with the path; the plugin
+reads the program and returns a stream whose `frame()` the SDK pulls on
+the audio clock, one 1/60 s frame per call. `started` runs once the
+stream plays; `signal` aborts the read when the open is replaced or
+closed.
+```ts
+plugin.resolvers.add({
+  id: "chip8",
+  extensions: ["ch8"], // lower case, no dot; matches Game.CH8 too
+  async resolve(path, signal) {
+    const frame = emulator(await readFile(path, { signal }));
+    return {
+      kind: "stream",
+      width: 64, // CHIP-8's display
+      height: 32,
+      frame,
+      started: (stream) => stream.onStop((error) => error && plugin.osd.show(error.message)),
+    };
+  },
+});
+```
+
 ### ResolvedStream
 
 What a file resolver returns: a stream, with the same frame contract as
@@ -6159,6 +8441,18 @@ interface Resolvers {
    * The extensions some plugin's file resolver handles (SDK 1.5.8, player 0.4.2): lower case, without the dot, sorted, each once; not who registered them. Reading needs no capability; `[]` from older players. Without `events` it is the list from when the plugin first read it. Use it to accept such files beside the player's own media types, for example in a playlist's drop or folder scan.
    * @capability None.
    * @player 0.4.2
+   * @example Accept files that a resolver plugin can play
+   * A plugin's own file filter also accepts types other plugins turn into
+   * streams. `fileTypes` lists the extensions every running file resolver
+   * claims (lower case, no dot); the SDK keeps it current with `events`.
+   * ```ts
+   * const MEDIA = ["mp4", "mkv", "mp3"];
+   * // Extensions compare in lower case, without the dot.
+   * const accepted = (path: string) => {
+   *   const extension = path.split(".").pop()?.toLowerCase() ?? "";
+   *   return MEDIA.includes(extension) || plugin.resolvers.fileTypes.includes(extension);
+   * };
+   * ```
    */
   readonly fileTypes: readonly string[];
   /**
@@ -6167,11 +8461,40 @@ interface Resolvers {
    * @returns A handle that removes the listener.
    * @capability `events`
    * @player 0.4.2
+   * @example Say which file types became playable
+   * When a plugin with a file resolver starts or stops, the OSD lists the
+   * extra file types now accepted. The listener (which needs `events`)
+   * receives the new list each time it changes.
+   * ```ts
+   * plugin.resolvers.onFileTypesChange((types) => {
+   *   void plugin.osd.show("Also accepted: {}", [plugin.i18n.list(types)]);
+   * });
+   * ```
    */
   onFileTypesChange(listener: (types: string[]) => void): Disposable;
 }
 ```
 
+Example: Play pages of a video site
+
+Opening a `https://video.example.com/…` page plays its video. When the
+user opens a URL whose scheme and host this resolver declares, the
+player asks the plugin first; `resolve` returns the stream's address,
+and `signal` aborts the lookup when the open is replaced or closed.
+```ts
+plugin.resolvers.add({
+  id: "example",
+  schemes: ["https"],
+  hosts: ["video.example.com"],
+  async resolve(url, signal) {
+    const response = await fetch(url, { signal }); // the site's JSON for the page
+    if (!response.ok) throw new Error(`video.example.com answered ${response.status}`);
+    const page = await response.json();
+    return { kind: "media", originalUrl: url, title: page.title, primary: { url: page.stream } };
+  },
+});
+```
+
 ### PackageManifest
 
 The manifest of a package, as validated. The display fields and
@@ -6440,6 +8763,21 @@ interface Packages {
 }
 ```
 
+Example: Install a plugin from an unpacked package
+
+The plugin installs a package directory it downloaded and unpacked, and
+reports why when it does not work. `validate` asks the player to check
+the package and returns a candidate; `install` starts the change and
+`done` resolves with its final status: `committed` only once the new
+plugin reported that it is running, otherwise `failed`, `cancelled`,
+`failedDegraded` or `tooLate`.
+```ts
+const candidate = await plugin.packages.validate(unpackedDirectory);
+const change = await candidate.install();
+// `message` says why a change did not commit.
+if ((await change.done) !== "committed") throw new Error(change.message ?? "install failed");
+```
+
 ### BindingRef
 
 A command: manifest id (`"host"` for the player's own) and command id.
@@ -6517,6 +8855,18 @@ interface Bindings {
 }
 ```
 
+Example: Unbind the player's Mute key, then restore it
+
+The player's Mute command loses its default key, and later gets it
+back. `set` with `[]` saves an override that unbinds the command
+(remembered across launches); `reset` removes the override, so the
+command's own default bindings apply again.
+```ts
+await plugin.bindings.set({ plugin: "host", command: "mute" }, []);
+// later
+await plugin.bindings.reset({ plugin: "host", command: "mute" });
+```
+
 ### Clipboard
 
 The system clipboard (`clipboard`). Unavailable without a user interface.
@@ -6537,6 +8887,21 @@ interface Clipboard {
 }
 ```
 
+Example: Copy the current file and position
+
+The clipboard holds "path @ seconds" for pasting into a note. The
+player writes the system clipboard; it rejects with `unsupported` on
+systems other than macOS and Windows and `failed` when the system
+refuses, which the plugin reports.
+```ts
+const { source, position } = plugin.player.state;
+try {
+  await plugin.clipboard.writeText(`${source} @ ${position}`); // data, not shown
+} catch (error) {
+  void plugin.osd.show("Could not copy: {}", [(error as PluginError).code]);
+}
+```
+
 ### Power
 
 Keeping the computer awake (`playback.control`).
@@ -6598,6 +8963,25 @@ interface Tools {
 }
 ```
 
+Example: Read a file's format with ffprobe
+
+The plugin gets a media file's container details as JSON. `available`
+says whether ffprobe can be found (`VESTRA_FFPROBE`, then `PATH`); `run`
+starts it from the plugin's own process without a shell and resolves
+with its output as bytes once it exits, or rejects when it fails
+(`failed`, with the last stderr line) or takes longer than `timeoutMs`.
+```ts
+if (await plugin.tools.available("ffprobe")) {
+  const { stdout } = await plugin.tools.run(
+    "ffprobe",
+    ["-v", "error", "-show_format", "-of", "json", path],
+    { timeoutMs: 10_000 }, // give up on a stuck file after 10 s
+  );
+  const info = JSON.parse(new TextDecoder().decode(stdout));
+  void info.format; // container, duration, bit rate…
+}
+```
+
 ### JsonStore
 
 A JSON file `dataDirectory/<name>.json`, loaded once and saved debounced.
@@ -6627,6 +9011,22 @@ interface Storage {
    *
    * The file is read synchronously on creation; `debounceMs` defaults to
    * 300. Files are created with mode 0600. `invalid` for a bad name.
+   * @example Keep settings and a recent list in a JSON file
+   * The plugin remembers whether to resume and the last ten files across
+   * restarts. `json` reads `settings.json` from the data directory at once
+   * (or uses `defaults` when it is missing or fails `validate`); `save`
+   * replaces the value and writes the file 300 ms later, and stopping the
+   * plugin writes a pending save first.
+   * ```ts
+   * type Settings = { resume: boolean; recent: string[] };
+   * const store = plugin.storage.json<Settings>("settings", {
+   *   defaults: { resume: true, recent: [] },
+   *   validate: (v): v is Settings =>
+   *     typeof v === "object" && v !== null && typeof (v as Settings).resume === "boolean",
+   * });
+   * // Only `save` writes: changing `store.value` in place is not saved.
+   * store.save({ ...store.value, recent: [path, ...store.value.recent].slice(0, 10) });
+   * ```
    */
   json<T>(name: string, options: {
     defaults: T;
@@ -6700,6 +9100,20 @@ interface SessionStorage {
 }
 ```
 
+Example: Keep a work queue across a plugin restart
+
+A download queue survives the plugin being reloaded or crashing, and is
+empty again when the player starts next time. Session storage lives in
+the player process for one player run; each `set` is kept once its
+promise resolves, so nothing is lost if the plugin dies right after.
+```ts
+// A queue the plugin is working through: after a reload or a crash it
+// goes on where it stopped, after the player quits it starts afresh.
+const pending = (await plugin.storage.session.get<string[]>("queue")) ?? [];
+pending.push("https://example.com/a.mkv");
+await plugin.storage.session.set("queue", pending);
+```
+
 ### System
 
 `plugin.system`: files and links, executed by the player. No capability.
@@ -6718,6 +9132,22 @@ interface System {
 }
 ```
 
+Example: Show an exported file and open the help page
+
+The file manager opens with the exported file selected, then the
+browser opens the plugin's help page. The player performs both on the
+plugin's behalf; they reject with `unsupported` on systems other than
+macOS and Windows, which the plugin turns into a message.
+```ts
+try {
+  await plugin.system.reveal(exportedFile);
+  await plugin.system.openUrl("https://example.com/help");
+} catch (error) {
+  if ((error as PluginError).code !== "unsupported") throw error;
+  await plugin.osd.show(`Saved to ${exportedFile}`); // no file manager to open
+}
+```
+
 ### Secrets
 
 Per-plugin secrets (API keys, passwords) in the system's secret store:
@@ -6741,6 +9171,27 @@ interface Secrets {
 }
 ```
 
+Example: Ask for an API token once and keep it in the keychain
+
+The user types the token the first time; later runs read it from the
+system's secret store. `get` resolves `null` when nothing is stored; a
+store that is missing or refuses access rejects (`unsupported`,
+`unavailable`, `failed`), and then the plugin keeps the token for this
+run only and asks again next time.
+```ts
+let token: string | null = null;
+try {
+  token = await plugin.secrets.get("api-token");
+} catch {
+  // No usable store: fall through and ask.
+}
+if (token === null) {
+  token = await askUser();
+  if (token)
+    await plugin.secrets.set("api-token", token).catch(() => {}); // best effort
+}
+```
+
 ### VideoNode
 
 One node of a VideoFilter chain, by `kind`. Values outside the
@@ -6879,6 +9330,24 @@ type VideoNode =
 };
 ```
 
+Example: Brighten, sharpen and rotate the picture
+
+The video plays a little brighter and more saturated, slightly sharper
+and turned a quarter clockwise. The nodes run in array order; `set` sends
+the whole chain as this plugin's desired value (last write wins), and the
+player applies it to every source until it changes, needing
+`processing.video`, `playback.read` and `events`.
+```ts
+const chain: VideoNode[] = [
+  // Live fields: moving them later changes the picture in place.
+  { kind: "eq", brightness: 0.05, contrast: 1.1, saturation: 1.2, gamma: 1 },
+  // Not live: changing `amount` later rebuilds the stage (a one-frame stall).
+  { kind: "sharpen", amount: 0.5, size: "small" },
+  { kind: "transform", rotate: 90, flipH: false, flipV: false },
+];
+plugin.video.filter("picture").set(chain);
+```
+
 ### AudioNode
 
 One node of an AudioFilter chain, by `kind`. Values outside the
@@ -6935,6 +9404,22 @@ type AudioNode =
 };
 ```
 
+Example: Lift the voices and play in mono
+
+Speech around 1 kHz is 3 dB louder and both speakers play the same mixed
+channel. `set` sends this plugin's whole audio chain (the nodes in order,
+plus an optional `delayMs`); the player joins it with other plugins'
+chains and applies it to every source (`processing.audio`,
+`playback.read`, `events`).
+```ts
+plugin.audio.filter("sound").set({
+  nodes: [
+    { kind: "equalizer", frequency: 1000, q: 1, gainDb: 3 }, // +3 dB at 1 kHz
+    { kind: "channels", mode: "mono" }, // both channels get (L + R) / 2
+  ],
+});
+```
+
 ### ResolvedMedia
 
 What a resolver returns (WebResolverOptions.resolve): the playable
@@ -6956,12 +9441,50 @@ type ResolvedMedia = {
 };
 ```
 
+Example: Play a page whose video and audio are separate streams
+
+Opening a `https://video.example/…` page plays it with its title. When
+the user opens a URL whose scheme and host a web resolver declares, the
+player calls its `resolve(url, signal)`; the plugin looks up the streams
+and returns them, and the player plays `primary` with the separate
+`audio` track, sending the `headers` with every request for both.
+```ts
+plugin.resolvers.add({
+  id: "video-example",
+  schemes: ["https"],
+  hosts: ["video.example"],
+  async resolve(url, signal) {
+    // The site's own API (made up here) names the streams of a page.
+    const api = `https://video.example/api/streams?page=${encodeURIComponent(url)}`;
+    const response = await fetch(api, { signal });
+    // The player shows a failed resolve's message to the user.
+    if (!response.ok)
+      throw new Error(`video.example answered ${response.status} for this page`);
+    const info = (await response.json()) as {
+      title: string;
+      video: string;
+      audio: string;
+    };
+    const headers = { Referer: url }; // identical for both streams
+    const media: ResolvedMedia = {
+      kind: "media",
+      originalUrl: url,
+      title: info.title,
+      primary: { url: info.video, headers },
+      audio: { url: info.audio, headers },
+    };
+    return media;
+  },
+});
+```
+
 ### SubtitleStyle
 
 A subtitle style layer (Subtitles.setStyle). Sizes are at the
-1080p reference height and scale with the video. The effective style is
-the layer of the plugin that set one last; it also applies to the
-secondary subtitle.
+1080p reference height and scale with the video. Each plugin has one
+layer; when several plugins set one, the effective style is the layer of
+the plugin whose manifest id sorts last (the order of the calls does not
+matter). It also applies to the secondary subtitle.
 
 ```ts
 type SubtitleStyle = {
@@ -6992,6 +9515,30 @@ type SubtitleStyle = {
 };
 ```
 
+Example: Show large yellow subtitles a quarter second earlier
+
+Subtitles turn yellow at size 44 on a 60 % opaque box, 6 % above the
+bottom of the video, and appear 250 ms earlier. `refresh` reads the
+subtitle state from the player, whose `fonts` lists the font ids a style
+may name; `setStyle` then sends this plugin's style layer
+(`subtitles.control`, `subtitles.read`). It shows unless another plugin
+with a manifest id that sorts later has a layer too: the player picks the
+effective layer by manifest id, not by which call came last.
+```ts
+const { fonts } = await plugin.subtitles.refresh();
+if (!fonts.length) return; // no font to name: leave the style alone
+const style: SubtitleStyle = {
+  fontId: fonts[0]!.id, // a font the player offers
+  fontSize: 44, // at the 1080p reference height; scales with the video
+  color: "yellow",
+  outline: 2,
+  marginPercent: 6, // bottom margin, % of the video height
+  offsetMs: -250, // negative: shown earlier
+  box: 60, // background box opacity
+};
+await plugin.subtitles.setStyle(style);
+```
+
 ### Json
 
 A JSON value: what crosses the wire to the player. Slint property values,
@@ -7067,6 +9614,22 @@ interface FakeWindow {
 }
 ```
 
+Example: Change a setting in a tool window from a test
+
+The test opens the plugin's Picture window, moves its brightness control
+and checks that the plugin wrote the value back. `emit` fires a Slint
+callback as if the user used the control; the plugin's `on` handler runs
+and sets properties, which reach the host as requests, so `settle()`
+waits for them before `props` is read.
+```ts
+await host.command("open-picture").run(); // the plugin calls window.show()
+const picture = host.window("picture");
+assert.equal(picture.visible, true);
+picture.emit("adjust", "brightness", 40); // fire a Slint callback
+await host.settle();
+assert.equal(picture.props["brightness"], 40);
+```
+
 ### FileDialogText
 
 A file dialog as the player shows it (TestHost.fileDialogs).
@@ -7125,6 +9688,21 @@ interface FakeCommand {
 }
 ```
 
+Example: Run a checkable menu item from a test
+
+The test checks the Loop item's menu place, picks it and sees its check
+mark turn on. `host.command(id)` is the host's record of what the plugin
+declared and the state it last sent; `run()` calls the plugin's `run`
+like the menu, after which the SDK re-evaluates the command's state and
+sends it, and `run()` resolves once the host is idle again.
+```ts
+const toggle = host.command("toggle-loop");
+assert.deepEqual(toggle.declaration.path, ["Playback", "Loop"]);
+assert.equal(toggle.state.checked, false);
+await toggle.run();
+assert.equal(host.command("toggle-loop").state.checked, true);
+```
+
 ### FakeBarButton
 
 A command's bottom-bar button (`CommandOptions.button`) as the player shows
@@ -7261,6 +9839,16 @@ class TestHost implements Transport {
   readonly coreCommands: Map<string, FakeCommand>;
   /**
    * Both panel positions as the player reports them (`null` while no panel is mounted there). You may change a slot directly and then call `host.emit("window.state", {})` to simulate a change made elsewhere.
+   * @example Hide the sidebar and check the player's layout
+   * With the plugin's panel in the sidebar, toggling the sidebar records
+   * that the user prefers it hidden. `toggle()` reads the slot from the
+   * player, asks for the opposite of its `preferred` flag and resolves once
+   * the player answered, so the host's `layout` already shows the new value.
+   * ```ts
+   * assert.equal(host.layout.sidebar?.preferred, true);
+   * await plugin.panels.sidebar.toggle();
+   * assert.equal(host.layout.sidebar?.preferred, false);
+   * ```
    */
   readonly layout: {
     /** The bottom bar position: `preferred`, `effective`, `reason`, `detached`, `owner` and `panels` (its one panel). */
@@ -7289,6 +9877,17 @@ class TestHost implements Transport {
    * `"zh-Hans"`. While `locale` was never set they stay in Chinese, as
    * players up to 0.4.2 showed them, so tests written for SDK 1.5.8 keep
    * passing; set `locale` to test what a user sees now.
+   * @example Check a menu path in Simplified Chinese
+   * The test starts the plugin with a Chinese interface and checks the
+   * menu path its Blur item shows. The `locale` option sets
+   * `host.locale` before activation, so the plugin's `locales/zh-Hans.po`
+   * is loaded; the built-in menu `@video` shows in the player's own words
+   * (视频), the item's title in the plugin's translation.
+   * ```ts
+   * const { host, stop } = await startPlugin(activate, { directory, locale: "zh-Hans" });
+   * assert.deepEqual(host.command("blur").display.path, ["视频", "模糊…"]);
+   * await stop();
+   * ```
    */
   get locale(): Locale;
   set locale(locale: Locale);
@@ -7302,6 +9901,13 @@ class TestHost implements Transport {
    * @param text - English source text or template.
    * @param args - Values for its placeholders.
    * @returns The shown text.
+   * @example Compare with a translated message
+   * The test expects the text a Chinese user sees for a template the plugin
+   * shows. `translate` looks the English source up in the plugin's catalog
+   * for `host.locale` and fills in the arguments, the way the player does.
+   * ```ts
+   * assert.equal(host.translate("Speed {}×", [2]), "倍速 2×");
+   * ```
    */
   translate(text: TextValue, args?: TemplateArgs): string;
   /** The saved interface language (`plugin.appearance.language`), changed by `appearance.setLanguage` or TestHost.setLanguage. */
@@ -7337,7 +9943,20 @@ class TestHost implements Transport {
     /** The provider's `canPrevious`, as last evaluated. */
     canPrevious: boolean;
   } | null;
-  /** What `player.stats()` returns. Fields added in later rounds may be left out; the SDK fills them with `null`. */
+  /**
+   * What `player.stats()` returns. Fields added in later rounds may be left out; the SDK fills them with `null`.
+   * @example Pretend a 1080p H.264 video is playing
+   * The plugin's `player.stats()` now reports a 1920×1080 H.264 stream at
+   * 24 fps. The host answers `stats()` with this object as it stands, so a
+   * test sets it before the plugin asks; fields it leaves out come back as
+   * `null` from the SDK.
+   * ```ts
+   * host.stats = {
+   *   ...host.stats, // keep the other fields
+   *   video: { codec: "h264", width: 1920, height: 1080, fps: 24 },
+   * } as typeof host.stats;
+   * ```
+   */
   stats: PlaybackStats;
   /** Every `subtitles.load`: its options and bytes, newest last. */
   readonly subtitleLoads: {
@@ -7359,7 +9978,27 @@ class TestHost implements Transport {
   };
   /** The effective `power.preventSleep` mode. */
   power: "off" | "playing";
-  /** The fake `ffmpeg` / `ffprobe` behind `plugin.tools`. A tool without a handler is not found (`available()` is false, `run()` rejects with `unavailable`). */
+  /**
+   * The fake `ffmpeg` / `ffprobe` behind `plugin.tools`. A tool without a handler is not found (`available()` is false, `run()` rejects with `unavailable`).
+   * @example Fake ffprobe and a failing ffmpeg
+   * The plugin's Probe command gets an empty stream list from ffprobe, and
+   * any ffmpeg run fails as it would on a broken file. `handle` makes the
+   * tool available and answers each `tools.run` with the handler's result;
+   * a thrown `HostError` makes the run reject with that code. `calls`
+   * records every run with its arguments.
+   * ```ts
+   * host.tools.handle("ffprobe", (args) => {
+   *   assert.ok(args.includes("-show_streams")); // what the plugin asked for
+   *   return { stdout: JSON.stringify({ streams: [] }) }; // a file with no streams
+   * });
+   * // Every ffmpeg run rejects with code `failed`.
+   * host.tools.handle("ffmpeg", () => {
+   *   throw new HostError("failed", "Invalid data found when processing input");
+   * });
+   * await host.command("probe").run();
+   * assert.equal(host.tools.calls[0]?.tool, "ffprobe");
+   * ```
+   */
   readonly tools: {
     /** Every run: the tool name and its arguments, newest last. */
     calls: {
@@ -7432,6 +10071,20 @@ class TestHost implements Transport {
    * Simulate another plugin publishing its timeline layer (or clearing it with `[]`); pushes `timeline.changed` when the plugin subscribed.
    * @param pluginId - The other plugin's manifest id.
    * @param marks - Its whole layer.
+   * @example Let another plugin publish chapters
+   * The plugin under test sees two chapter marks another plugin put on the
+   * timeline. `setTimelineLayer` stores that plugin's whole layer and pushes
+   * `timeline.changed`; once the plugin uses `plugin.timeline` (with
+   * `events`) the SDK keeps `marks` current from that event, and `settle()`
+   * lets it arrive.
+   * ```ts
+   * host.setTimelineLayer("community.chapters", [
+   *   { time: 0, kind: "chapter", title: "Intro" },
+   *   { time: 95, kind: "chapter", title: "Part 1" },
+   * ]); // replaces that plugin's whole layer; [] would clear it
+   * await host.settle();
+   * assert.equal(plugin.timeline.marks.length, 2);
+   * ```
    */
   setTimelineLayer(pluginId: string, marks: {
     time: number;
@@ -7451,6 +10104,16 @@ class TestHost implements Transport {
   }[];
   /**
    * The file an image property shows, or `null` when the value is not a runtime image. View properties hold images in their wire form; this reads the path back.
+   * @example Check which file a window shows as its cover
+   * The test checks that the Cover window's image comes from the plugin's
+   * data directory. An image property holds the SDK's wire form of
+   * `plugin.ui.image(path)`, not a path; `imagePath` reads the path back.
+   * ```ts
+   * assert.equal(
+   *   host.imagePath(host.window("cover").props["cover"]),
+   *   join(plugin.dataDirectory, "cover.png"),
+   * );
+   * ```
    */
   imagePath(value: Json | undefined): string | null;
   /** `drops.provide` registrations of this plugin, in order (`id` is the SDK's). */
@@ -7463,9 +10126,24 @@ class TestHost implements Transport {
   /** The panel has an `onDrop` listener. */
   panelDrops: boolean;
   /**
-   * Drop files like the player: on a panel with an `onDrop` listener the whole list goes there; otherwise (and on the video area) grouped by extension to the first provider (`folder` for existing directories). Files nobody takes are ignored. Resolves once the host is idle again.
+   * Drop files like the player: on a panel with an `onDrop` listener the whole list goes there; otherwise (and on the video area) each path goes to the first provider of its extension (`folder` for existing directories), one call per provider with all of its paths. Files nobody takes are ignored. Resolves once the host is idle again.
    * @param paths - The dropped paths, in the order the file manager gives.
    * @param options - `target`: `"video"` (default) or `"panel"`; `at`: the drop point in panel coordinates (default `{ x: 0, y: 0 }`); `modifiers`: keys held (default all `false`).
+   * @example Drop files on the video and on the panel
+   * The first drop lands on the video area: each extension belongs to the
+   * provider that registered it first, and each provider gets one call with
+   * all of its paths. The second lands on the panel at a point, with Alt
+   * held, and the panel's `onDrop` gets the whole list. `drop` resolves
+   * once the host is idle.
+   * ```ts
+   * await host.drop(["/media/a.srt", "/media/b.mkv"]); // on the video area
+   * // On the panel, 10 px from its left and 48 px from its top, Alt held.
+   * await host.drop(["/media/list.m3u"], {
+   *   target: "panel",
+   *   at: { x: 10, y: 48 },
+   *   modifiers: { alt: true },
+   * });
+   * ```
    */
   drop(paths: string[], options?: {
     target?: "video" | "panel";
@@ -7511,7 +10189,20 @@ class TestHost implements Transport {
     /** Whether the options window is open. */
     open: boolean;
   };
-  /** One settings page by id. Throws when it was never registered. */
+  /**
+   * One settings page by id. Throws when it was never registered.
+   * @example Change a value on the plugin's settings page
+   * The test sets the step on the General page and checks the page shows
+   * it. `emit` fires the page's callback as the user's input would; the
+   * plugin's handler stores the value and its `bind` function sends it back
+   * as a property, which `settle()` waits for.
+   * ```ts
+   * const page = host.settingsPage("general");
+   * page.emit("setStep", 10);
+   * await host.settle();
+   * assert.equal(page.props["step"], 10);
+   * ```
+   */
   settingsPage(id: string): {
     /** The page's settings category. */
     category: string;
@@ -7544,6 +10235,18 @@ class TestHost implements Transport {
    * @param slot - The position.
    * @param plugin - The other plugin's manifest id.
    * @param options - `title`: its tab label (default: `plugin`).
+   * @example Put the playlist next to this plugin's sidebar panel
+   * The sidebar ends up with two tabs: the playlist, mounted first, and the
+   * plugin's own panel after it. `mountOther` before `startPlugin` mounts
+   * another plugin's panel as the player would, so the plugin's mount
+   * during activation becomes the second tab (in the bottom bar or the
+   * backdrop it would be refused with `conflict` instead).
+   * ```ts
+   * const host = new TestHost();
+   * host.mountOther("sidebar", "vestra.playlist", { title: "播放列表" });
+   * await startPlugin(activate, { host, directory });
+   * assert.equal(host.layout.sidebar?.panels?.length, 2);
+   * ```
    */
   mountOther(slot: "bottom" | "sidebar" | "backdrop", plugin: string, options?: {
     title?: string;
@@ -7582,10 +10285,32 @@ class TestHost implements Transport {
   setVideoRenderOwner(pluginId: string | null): void;
   /**
    * What the player pushes when mpv cannot compile a shader (code `failed`) or switches to software rendering (`unsupported`, which also sets `videoRender.gpu` to false). Pushed only when this plugin is the owner.
+   * @example Make a shader fail to compile
+   * The plugin's render options report `failed`, as when mpv rejects a
+   * shader. The host pushes the failure only while this plugin owns the
+   * render options, which its first accepted `set` made it; the SDK updates
+   * the handle's `status` when the push arrives, so the test settles first.
+   * ```ts
+   * const render = plugin.video.render();
+   * render.set({ toneMapping: "bt.2390" }); // makes the plugin the owner
+   * await host.settle();
+   * host.failVideoRender("failed", "shader compile failed: ERROR: 0:39: ...");
+   * await host.settle();
+   * assert.equal(render.status.state, "failed");
+   * ```
    */
   failVideoRender(code: "failed" | "unsupported", message: string): void;
   /**
    * The player's processing (filter) state. Wire-level; may change in minor versions. `resources` holds each `video.filter` / `audio.filter` chain the plugin applied, keyed by the SDK's resource id.
+   * @example Check the filter chain the plugin applied
+   * After the plugin set its picture chain, the test reads the one chain
+   * the host holds and compares its nodes. `resources` keeps each applied
+   * `video.filter` / `audio.filter` chain by the SDK's resource id, after
+   * the host validated it with the player's value ranges.
+   * ```ts
+   * const [chain] = [...host.processing.resources.values()];
+   * assert.deepEqual(chain?.nodes, [{ kind: "hue", degrees: 30 }]);
+   * ```
    */
   readonly processing: {
     /** Increases with every accepted change. */
@@ -7660,6 +10385,15 @@ class TestHost implements Transport {
   readonly resolvers: Map<string, Json>;
   /**
    * Resolvers other plugins hold, as `resolvers.add` declares them plus the holder's id: a registration of this plugin that claims one of their extensions (or scheme + host pairs) is refused with `conflict`, which does not fail activation, like the player.
+   * @example Start with another plugin holding a file type
+   * The plugin starts in a player where another plugin already resolves
+   * `.ch8` files. Pushed before `startPlugin`, the entry makes the plugin's
+   * own resolver for `.ch8` fail with `conflict` during activation, which
+   * (as in the player) does not fail the activation.
+   * ```ts
+   * const host = new TestHost();
+   * host.otherResolvers.push({ owner: "example.emulator", extensions: ["ch8"] });
+   * ```
    */
   readonly otherResolvers: {
     /** The manifest id of the plugin holding them (shown in the refusal). */
@@ -7675,6 +10409,17 @@ class TestHost implements Transport {
   fileTypes(): string[];
   /**
    * Push `resolvers.fileTypes` when TestHost.fileTypes changed: called after this plugin's resolvers come and go; call it yourself after changing TestHost.otherResolvers (another plugin started or stopped).
+   * @example Let another plugin's file type appear while running
+   * Another plugin starts and adds `.ch8`; the plugin under test then sees
+   * it in `resolvers.fileTypes`. Changing `otherResolvers` alone pushes
+   * nothing: `updateFileTypes` sends the new list as the player does when
+   * a plugin starts or stops, and `settle()` lets the SDK apply it.
+   * ```ts
+   * host.otherResolvers.push({ owner: "example.emulator", extensions: ["ch8"] });
+   * host.updateFileTypes();
+   * await host.settle();
+   * assert.deepEqual(plugin.resolvers.fileTypes, ["ch8"]);
+   * ```
    */
   updateFileTypes(): void;
   /**
@@ -7696,6 +10441,18 @@ class TestHost implements Transport {
    *
    * For `openFile` / `openDirectory` / `saveFile` queue a one-path array;
    * for `openFiles` any number of paths.
+   * @example Answer the plugin's dialogs in advance
+   * The plugin's Open command gets a picked file, then a cancelled file
+   * dialog, then a confirmed question. All answers share one queue, taken
+   * from the front in the order the plugin opens dialogs of any kind: if
+   * the next queued answer is missing or of the wrong kind, the dialog
+   * fails like a lost reply, so queue them in the order the plugin asks.
+   * ```ts
+   * host.dialogAnswers.push(["/media/movie.mkv"]); // openFile picks it
+   * host.dialogAnswers.push(null); // the next file dialog is cancelled
+   * host.dialogAnswers.push({ confirmed: true, checked: false }); // confirm
+   * await host.command("open").run();
+   * ```
    */
   readonly dialogAnswers: (string[] | null | {
     /** The user clicked the confirm button. */
@@ -7776,6 +10533,20 @@ class TestHost implements Transport {
   stepSeekKeyframes: boolean;
   /**
    * Test data: the keyframe times (seconds, ascending) of the current source, for keyframe step seeks. `null` (the default): none modelled, and step seeks are exact even with `stepSeekKeyframes`.
+   * @example Step forward to the next keyframe
+   * With keyframe step seeks on, Forward from 0:12 lands on the keyframe at
+   * 0:20, not at 0:17, and the OSD says so. `keyframes` gives the source's
+   * keyframe times; `setStepSeek` turns on keyframe steps of 5 s, and the
+   * core action `seek-forward` seeks to the first keyframe at or after
+   * the target, as the player does.
+   * ```ts
+   * host.setSource({ phase: "ready", duration: 45, position: 12 });
+   * host.keyframes = [0, 10, 20, 30, 40];
+   * await plugin.player.setStepSeek({ seconds: 5, keyframes: true });
+   * await plugin.host.run("seek-forward"); // target 17 s, next keyframe 20 s
+   * assert.equal(host.source.position, 20);
+   * assert.equal(host.osd.at(-1), "Forward 5 s: 00:20 / 00:45");
+   * ```
    */
   keyframes: number[] | null;
   /**
@@ -7811,6 +10582,17 @@ class TestHost implements Transport {
   readonly coreRuns: string[];
   /**
    * One of the 14 core actions (`play-pause`, `stop`, `seek-forward`, ...) that the test host registers like the player, as `host/<id>`. Throws for an unknown id. `run()` executes it with the player's checks and writes its on-screen text to TestHost.osd.
+   * @example Pause through the player's own action
+   * The test pauses playback the way the Space key does and checks that the
+   * host recorded it. Core actions belong to the player (`host/<id>`);
+   * `run()` applies the player's checks, so a source must be ready first,
+   * and every run is appended to `coreRuns`.
+   * ```ts
+   * host.setSource({ phase: "ready", duration: 100, position: 10 });
+   * await host.coreAction("play-pause").run();
+   * assert.equal(host.source.paused, true);
+   * assert.deepEqual(host.coreRuns, ["play-pause"]);
+   * ```
    */
   coreAction(id: string): FakeCommand;
   /**
@@ -7826,6 +10608,20 @@ class TestHost implements Transport {
    * find the one a call uses.
    * @param method - The wire method name.
    * @param handler - Produces the reply from the request parameters.
+   * @example Make opening a folder fail
+   * The plugin's Open Folder command meets a missing folder and must tell
+   * the user. `handle` replaces the host's answer to one wire method; the
+   * `HostError` it throws reaches the plugin as a rejection with code
+   * `missing`, like the player's refusal. `reset` restores the default
+   * behaviour for the rest of the test.
+   * ```ts
+   * host.handle("system.openPath", () => {
+   *   throw new HostError("missing", "no such file");
+   * });
+   * await host.command("open-folder").run(); // the plugin catches `missing`
+   * assert.deepEqual(host.osd, ["Folder not found"]);
+   * host.reset("system.openPath");
+   * ```
    */
   handle(method: string, handler: Handler): void;
   /** Restore the default behaviour of a method replaced with TestHost.handle. */
@@ -7839,10 +10635,34 @@ class TestHost implements Transport {
   /**
    * Change the source facts and broadcast them, as if the player's state changed (the user paused, playback reached the end, a file finished loading). Any phase other than `empty` also turns on the source capabilities (pause, seek, rate, ...) unless the patch sets them. `phase: "loading"` makes a mounted backdrop effective, like the player.
    * @param patch - Wire-level source fields, e.g. `phase`, `position`, `duration`, `paused`, `audioTracks`.
+   * @example Load a file, then let it play to the end
+   * The plugin sees a one-minute source become ready, then end on its own.
+   * `setSource` changes the host's source facts and broadcasts them like
+   * the player's events; the SDK updates `player.state` when the event
+   * arrives, so the test settles before reading it.
+   * ```ts
+   * host.setSource({ phase: "ready", duration: 60, position: 0 });
+   * await host.settle();
+   * assert.equal(plugin.player.state.phase, "ready");
+   * host.setSource({ phase: "ended", terminalReason: "natural" });
+   * await host.settle();
+   * ```
    */
   setSource(patch: Partial<SourceState>): void;
   /**
    * Simulate the user changing the main window (resizing it, entering or leaving fullscreen, closing the picture-in-picture window) and broadcast it. Like the player, entering fullscreen collapses an attached, visible sidebar (`effective: false`, `reason: "fullscreen"`) and leaving fullscreen docks it again.
+   * @example Go fullscreen, then report picture-in-picture support
+   * The plugin sees the main window fullscreen at 1920×1080, then learns
+   * that picture-in-picture is available. `setMainWindow` changes the
+   * host's window facts and broadcasts them as the player does when the
+   * user resizes or toggles fullscreen; entering fullscreen also collapses
+   * an attached sidebar.
+   * ```ts
+   * host.setMainWindow({ fullscreen: true, videoArea: { width: 1920, height: 1080 } });
+   * await host.settle();
+   * assert.equal(plugin.window.state.fullscreen, true);
+   * host.setMainWindow({ pictureInPicture: { supported: true, active: false } });
+   * ```
    */
   setMainWindow(patch: Partial<{
     fullscreen: boolean;
@@ -7863,22 +10683,61 @@ class TestHost implements Transport {
    * Simulate another plugin (or the user) opening a source: a new `sourceId`, then the given phase. Calls the plugin made against the old state now fail with `stale`.
    * @param source - The path or URL.
    * @param phase - The phase to end in (default `"ready"`).
+   * @example Let the user open another file meanwhile
+   * A state the plugin captured before stops being current once another
+   * file opens. `openElsewhere` gives the source a new `sourceId`, so
+   * `isCurrent` turns false. Promise-returning calls made with
+   * `ifCurrent: before` then reject with `stale`; calls that return nothing
+   * drop the write silently instead (`TimelineLayer.set` with `ifCurrent`).
+   * ```ts
+   * const before = plugin.player.state;
+   * host.openElsewhere("/media/other.mp4");
+   * await host.settle();
+   * assert.equal(plugin.player.isCurrent(before), false);
+   * ```
    */
   openElsewhere(source: string, phase?: SourceState["phase"]): void;
   /**
    * Simulate a generated stream failing in the player (its audio device lost, its frame connection broken), like the player: the source fails with `message` (`phase: "error"`) and the producer is retired at once. The stream's `onStop` listeners get a `stream` error with `message`.
    * @param producerId - The producer, from TestHost.producers.
    * @param message - The player's failure text.
+   * @example Break the plugin's generated stream
+   * The plugin's stream stops with an error, as when the player loses its
+   * audio device. `failStream` puts the source into `error` with the
+   * message and retires the producer at once; the stream's `onStop`
+   * listeners get a `stream` error carrying the message.
+   * ```ts
+   * const [producer] = host.producers.values();
+   * host.failStream(producer!.id, "producer transport closed");
+   * ```
    */
   failStream(producerId: number, message: string): void;
   /**
    * Press a binding like the host's table would: panel-focus bindings first when `panel` is true, then global ones; within a scope the earliest registration first (the player's own commands before the plugin's), as the conflict rule orders them. A disabled command lets the key pass to the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it shadowed, then the global scope. The first enabled one runs; `press` resolves after it ran (`"ran"`), or rejects when it is busy. When only disabled commands hold the key, the first one with a `reason` shows the reason on the OSD and eats the key (`"reason"`, see `host.osd`); without a reason the key goes on to the focused control (`"passed"`, nothing runs). Rejects when nothing is bound. Bindings use the reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user overrides in `bindings.overlay` apply.
    * @returns What the key did: `"ran"`, `"reason"` or `"passed"`.
+   * @example Press a global key and a panel key
+   * Ctrl+B runs whatever is bound globally; Delete is pressed while the
+   * plugin's panel has focus, so panel bindings are tried first. `press`
+   * follows the player's binding table and resolves with what happened:
+   * `"ran"`, `"reason"` (a disabled command showed why) or `"passed"`.
+   * ```ts
+   * await host.press("Ctrl+B"); // a global binding
+   * await host.press("Delete", { panel: true }); // while the panel has focus
+   * ```
    */
   press(binding: string, options?: {
     panel?: boolean;
   }): Promise<"ran" | "reason" | "passed">;
-  /** Bindings declared by more than one command, each as `[binding, winner, ...ignored]` (command ids; core actions as `host/<id>`). Empty when there are none. */
+  /**
+   * Bindings declared by more than one command, each as `[binding, winner, ...ignored]` (command ids; core actions as `host/<id>`). Empty when there are none.
+   * @example Check that no default keys collide
+   * The test fails when two commands, the player's or the plugin's, declare
+   * the same binding. Each entry is `[binding, winner, ...ignored]`, so an
+   * empty list means every key does what its command says.
+   * ```ts
+   * assert.deepEqual(host.conflicts, []);
+   * ```
+   */
   get conflicts(): string[][];
   /** The binding overlay `plugin.bindings.set` writes (`"<plugin>/<command>"` to inputs; preset it to simulate saved overrides). `press` honours it. */
   readonly bindings: {
@@ -7927,6 +10786,17 @@ class TestHost implements Transport {
   }[];
   /**
    * Packages `validate` and `validateArchive` accept: path (directory or `.vxp` file) → its manifest. Other paths fail with `missing`. `install` adds or upgrades the entry in TestHost.packages following the player's source rules: the same source upgrades, another source needs `replace` (`conflict` otherwise), a built-in id is `unsupported`.
+   * @example Offer a package file the plugin can install
+   * The plugin can validate and install `/downloads/someone.demo-1.0.0.vxp`
+   * as if the file existed. The host accepts only paths listed here (others
+   * fail with `missing`) and returns this manifest from `validate`; an
+   * install then follows the player's source rules.
+   * ```ts
+   * host.candidates.set("/downloads/someone.demo-1.0.0.vxp", {
+   *   id: "someone.demo", version: "1.0.0", apiVersion: "vestra/1",
+   *   entry: "main.js", capabilities: [],
+   * });
+   * ```
    */
   readonly candidates: Map<string, PackageManifest>;
   /**
@@ -7935,6 +10805,14 @@ class TestHost implements Transport {
   readonly remoteImages: Map<string, string | null>;
   /**
    * The Markdown document a value holds (its wire form read back), or `null` when the value is not one. `images` maps each remote address to the downloaded file. Pass a whole property value or a field of one: a document nested in rows is read the same way.
+   * @example Read back a Markdown message in a chat window
+   * The test checks the Markdown source of the first chat message. Rows
+   * hold the document in its wire form, as `plugin.ui.markdown` produced
+   * it; `markdown` reads it back, nested in a row or not.
+   * ```ts
+   * const rows = host.window("chat").props["messages"] as { body: Json }[];
+   * assert.equal(host.markdown(rows[0]!.body)?.text, "**Hello**");
+   * ```
    */
   markdown(value: Json | undefined): MarkdownWire | null;
   /** What `player.audioDevices()` lists. `setAudioDevice` updates `host.source.audioOutput`. */
@@ -7954,14 +10832,46 @@ class TestHost implements Transport {
   command(id: string): FakeCommand;
   /**
    * The plugin's bottom-bar buttons (`CommandOptions.button`) as the player shows them: at most one, the first declared (`BAR_BUTTON_LIMITS`; a later one stays a menu item only). Empty once the command is disposed. Whether the bar places them is the bar's business: the list is what the player hands to `BarButtons`.
+   * @example Click the plugin's bottom-bar button in a test
+   * The test finds the plugin's Store button, clicks it and checks that the
+   * Store window opened. `barButtons` lists the buttons of the plugin's
+   * commands declared with `button`, as the bar shows them; `click()` runs
+   * the command like its menu item and waits until the host is idle, and
+   * rejects while the command is disabled or busy.
+   * ```ts
+   * const [button] = host.barButtons; // one button per plugin
+   * assert.equal(button?.icon, "store");
+   * await button?.click();
+   * assert.equal(host.window("store").visible, true);
+   * ```
    */
   get barButtons(): readonly FakeBarButton[];
   /**
    * The plugin's tool window with this id (by default the file name without extension: `ui/picture.slint` → `picture`). Throws when it was never opened with `show()`.
+   * @example Press a window's Reset button from a test
+   * The Picture window's Reset callback runs and the brightness returns to
+   * 0. The window is found by its id (the `.slint` file name by default);
+   * `emit` fires the callback the plugin bound, and `settle()` waits for
+   * the property the handler wrote.
+   * ```ts
+   * host.window("picture").emit("reset");
+   * await host.settle();
+   * assert.equal(host.window("picture").props["brightness"], 0);
+   * ```
    */
   window(id: string): FakeWindow;
   /**
    * The plugin's mounted panel (bottom bar, sidebar or backdrop). Throws when none is mounted. Its `props` use Slint (kebab-case) names; `emit` fires a callback on the panel's global.
+   * @example Select a row in the plugin's sidebar panel
+   * The test checks the panel sits in the sidebar and selects its third
+   * row. `emit` fires a callback on the panel's global as a click would;
+   * the plugin's handler runs, and `settle()` waits for what it sent.
+   * ```ts
+   * const panel = host.mounted();
+   * assert.equal(panel.slot, "sidebar");
+   * panel.emit("select", 2);
+   * await host.settle();
+   * ```
    */
   mounted(): Omit<FakeWindow, "callbacks" | "userClose"> & {
     /** `"bottom"`, `"sidebar"` or `"backdrop"`. */
@@ -7971,7 +10881,16 @@ class TestHost implements Transport {
     /** The last `panel.setInteraction(...)` locks, `null` before any. */
     locks: Json;
   };
-  /** The parameters of every request of one wire method, oldest first. */
+  /**
+   * The parameters of every request of one wire method, oldest first.
+   * @example Check the request behind an OSD message
+   * The test checks the last OSD request the plugin sent, before
+   * translation. `sent` lists the parameters of every request of one wire
+   * method, oldest first; `host.osd` holds the texts as shown instead.
+   * ```ts
+   * assert.deepEqual(host.sent("osd.show").at(-1), { text: "Saved" });
+   * ```
+   */
   sent(method: string): Record<string, Json>[];
   /**
    * Wait until no request is in flight (and the SDK's follow-up passes ran),
@@ -7984,6 +10903,29 @@ class TestHost implements Transport {
    * for: on a loaded machine it can finish after `settle()` returns. Poll
    * the result you assert on instead (second example).
    * @param ms - Extra time to wait, for debounces and timers (default 0).
+   * @example Wait past a debounced save
+   * The plugin's store writes its file 300 ms after the last `save`, so
+   * the test waits 400 ms before it checks what the plugin did next.
+   * `settle(ms)` returns when no request is in flight and at least `ms`
+   * have passed, so the store's timer has fired. The file write itself is
+   * the plugin's own work, which `settle` does not wait for: a test that
+   * reads the file calls `await store.flush()` instead.
+   * ```ts
+   * const store = plugin.storage.json("prefs", { defaults: { step: 5 } });
+   * store.save({ step: 10 });
+   * await host.settle(400); // past storage.json's 300 ms debounce
+   * ```
+   * @example Poll for work the plugin does on its own
+   * The plugin reads and parses a file before it shows a status; `settle`
+   * does not wait for that (it only waits for host requests), so the test
+   * polls the property it asserts on, 20 ms at a time, for up to 2 seconds.
+   * ```ts
+   * const window = host.window("import");
+   * window.emit("load-file"); // the plugin reads and parses the file itself
+   * for (let i = 0; i < 100 && window.props["status-text"] !== expected; i++)
+   *   await host.settle(20);
+   * assert.equal(window.props["status-text"], expected);
+   * ```
    */
   settle(ms?: number): Promise<void>;
   /** Close the fake stream servers and delete the host's temporary directories. `stop()` from startPlugin calls it. */
@@ -7991,6 +10933,34 @@ class TestHost implements Transport {
 }
 ```
 
+Example: Preset the player, then react to another plugin's file
+
+The test starts the plugin in a player with the dark theme, opens a file
+the way another plugin would, and checks the plugin's panel title. A host
+created first can be preset with data the plugin reads during
+activation; `startPlugin` then uses it. `openElsewhere` changes the
+source and broadcasts it, the plugin's listener updates its panel, and
+`settle()` waits for those requests before the assertion.
+```ts
+import assert from "node:assert/strict";
+import test from "node:test";
+import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+import activate from "../main.ts";
+
+test("shows the playing file in the panel", async () => {
+  const host = new TestHost();
+  host.appearance = "vestra"; // read during activation
+  const { stop } = await startPlugin(activate, {
+    directory: new URL("..", import.meta.url),
+    host,
+  });
+  host.openElsewhere("/media/clip.mp4"); // another plugin opened a file
+  await host.settle();
+  assert.equal(host.mounted().props["title"], "clip.mp4");
+  await stop();
+});
+```
+
 ### startPlugin
 
 Activate a plugin against a test host, the way the player's runner does:
@@ -8044,6 +11014,47 @@ function startPlugin(activate: (plugin: Plugin) => unknown, options?: {
 }>;
 ```
 
+Example: Test that a setting survives a restart
+
+The test turns on the 10-step option, stops the plugin, starts it again
+on the same data directory and checks the option is still on. Both runs
+get a directory the test made (`dataDirectory`): `stop()` disposes the
+plugin like the player, which writes its pending stores there, and only
+removes the host's own temporary directory, so the second run reads what
+the first one saved.
+```ts
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { startPlugin } from "@vestra-player/sdk/testing";
+import activate from "../main.ts";
+
+test("remembers the step across restarts", async () => {
+  const directory = new URL("..", import.meta.url);
+  const data = mkdtempSync(join(tmpdir(), "data-"));
+  try {
+    const first = await startPlugin(activate, { directory, dataDirectory: data });
+    try {
+      await first.host.command("step-10").run();
+    } finally {
+      await first.stop(); // flushes the plugin's stores into `data`
+    }
+
+    // A restart: a new host and a new plugin instance on the same data.
+    const second = await startPlugin(activate, { directory, dataDirectory: data });
+    try {
+      assert.equal(second.host.command("step-10").state.checked, true);
+    } finally {
+      await second.stop();
+    }
+  } finally {
+    rmSync(data, { recursive: true, force: true });
+  }
+});
+```
+
 ### CapabilityInfo
 
 What one manifest capability is for: the members it opens, the
@@ -8090,6 +11101,27 @@ and `plugin.packages.list`).
 const CAPABILITY_INFO: Readonly<Record<string, CapabilityInfo>>;
 ```
 
+Example: Check in a test that the manifest declares every required capability
+
+The test fails, naming the missing capability, when the manifest declares
+a capability without one its members also need. It reads the plugin's own
+`manifest.json` and looks each declared name up in `CAPABILITY_INFO`,
+whose `requires` lists the capabilities that must be declared with it;
+at run time the player would refuse such a call with code `capability`.
+```ts
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { CAPABILITY_INFO } from "@vestra-player/sdk/testing";
+
+const manifest: { capabilities: string[] } = JSON.parse(
+  await readFile(new URL("../manifest.json", import.meta.url), "utf8"),
+);
+for (const capability of manifest.capabilities)
+  // An unknown name has no entry: `vestra-plugin check` reports it.
+  for (const needed of CAPABILITY_INFO[capability]?.requires ?? [])
+    assert.ok(manifest.capabilities.includes(needed), needed);
+```
+
 ### MESSAGE_LIMIT
 
 The longest message a plugin may send the player, in UTF-8 bytes of one
@@ -8106,8 +11138,9 @@ const MESSAGE_LIMIT: number;
 
 The player's command registry caps, the same values as the player's own
 table (the player's tests check that they agree). They are runaway guards,
-not product limits: a command added past them fails with code `limit`
-(its `ready` rejects; during activation, activation fails), commands
+not product limits: a command added past them is refused by the player
+with code `limit` (its `ready` rejects; during activation, activation
+fails; later the failure goes to `Scope.onError`), commands
 already registered are unaffected, and disposing a command frees its slot
 at once. TestHost enforces the same caps.
 
@@ -8123,6 +11156,22 @@ const COMMAND_LIMITS: {
 };
 ```
 
+Example: Cap a chapter menu well below the command limit
+
+The Chapters submenu lists at most 50 chapters, however many the file
+has. Every menu item is a command, and the player counts them per plugin.
+`add` itself returns at once and never throws `limit`: past `perPlugin`
+the player refuses the registration, which fails the activation or, later,
+reaches `Scope.onError`. A try/catch around `add` cannot catch that, so a
+menu built from media content keeps its own cap and leaves room for the
+plugin's fixed commands.
+```ts
+import { COMMAND_LIMITS } from "@vestra-player/sdk/testing";
+
+// 20 slots stay free for the plugin's own commands.
+const shown = chapters.slice(0, Math.min(50, COMMAND_LIMITS.perPlugin - 20));
+```
+
 ### MENU_IDS
 
 The player's built-in top-level menus, by id. Write `@<id>` as the first
@@ -8137,6 +11186,21 @@ agrees with the player's.
 const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings"];
 ```
 
+Example: Put a command into the built-in Video menu
+
+"Blur" appears in the player's Video menu in every interface language.
+The player replaces a leading `@video` with that menu's key ("Video")
+before it merges paths, so the item joins the built-in menu; an id that
+is not in `MENU_IDS` makes `add` fail with `invalid`, which a test can
+rule out ahead of time.
+```ts
+import assert from "node:assert/strict";
+import { MENU_IDS } from "@vestra-player/sdk/testing";
+
+plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run() {} });
+assert.ok(MENU_IDS.includes("video")); // a menu id, not a title
+```
+
 ### BAR_BUTTON_ICONS
 
 The icons a bottom-bar button may name (`CommandOptions.button.icon`):
@@ -8148,6 +11212,19 @@ that this list is its icon set.
 const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back", "forward", "open", "volume", "mute", "playlist", "detach", "attach", "close", "failed", "move-top", "move-up", "move-down", "move-bottom", "search", "chapter", "bookmark", "check-task", "check-box", "menu-check", "submenu", "scroll-up", "scroll-down", "caret-down", "sort-asc", "sort-desc", "tag-remove", "preview-play", "add", "remove", "sort", "fullscreen", "exit-fullscreen", "store", "ai"];
 ```
 
+Example: Check in a test that the button's icon exists
+
+The test fails before release if the plugin's bar button names an icon
+the player does not have. `commands.add` would refuse an unknown name
+with `invalid`; the player's tests keep `BAR_BUTTON_ICONS` equal to its
+icon set, so checking against it is the same check without a player.
+```ts
+import assert from "node:assert/strict";
+import { BAR_BUTTON_ICONS } from "@vestra-player/sdk/testing";
+
+assert.ok(BAR_BUTTON_ICONS.includes("store")); // the icon main.ts uses
+```
+
 ### BAR_BUTTON_LIMITS
 
 The player's limits on bottom-bar buttons (`CommandOptions.button`), the
@@ -8201,6 +11278,25 @@ built-in plugins declare.
 const BUILTIN_SUBMENUS: readonly BuiltinSubmenu[];
 ```
 
+Example: Add an item to the built-in Snapshot submenu
+
+"Copy Snapshot" appears in Video ▸ Snapshot next to the built-in capture
+plugin's items. Paths merge by their English keys, so a command whose
+path continues with the submenu's keys (`["Video", "Snapshot"]`, the menu
+written as `@video`) lands in the same submenu whatever the interface
+language.
+```ts
+import { BUILTIN_SUBMENUS } from "@vestra-player/sdk/testing";
+
+const snapshot = BUILTIN_SUBMENUS.find((menu) => menu.path.at(-1) === "Snapshot")!;
+plugin.commands.add({
+  id: "snapshot-to-clipboard",
+  // ["@video", "Snapshot", "Copy Snapshot"]; @video stands for "Video".
+  path: ["@video", ...snapshot.path.slice(1), "Copy Snapshot"],
+  run: copySnapshot,
+});
+```
+
 ### BuiltinCommand
 
 A command the player or one of its built-in plugins registers: an entry
@@ -8240,6 +11336,22 @@ list agrees with what the player and its built-in plugins register.
 const BUILTIN_COMMANDS: readonly BuiltinCommand[];
 ```
 
+Example: Check in a test that a default key is still free
+
+The test fails if the player or a built-in plugin already binds Ctrl+K
+globally, before users ever see a conflict. It collects the default
+bindings of every built-in command that is not limited to its panel's
+focus (`focus: null`) and looks for the key the plugin wants; bindings
+are canonical, so compare them as the player writes them.
+```ts
+import assert from "node:assert/strict";
+import { BUILTIN_COMMANDS } from "@vestra-player/sdk/testing";
+
+const taken = BUILTIN_COMMANDS.filter((command) => command.focus === null)
+  .flatMap((command) => command.bindings);
+assert.ok(!taken.includes("Ctrl+K"));
+```
+
 ### LOCALES
 
 The player's interface languages: English (the source language) first,
@@ -8299,6 +11411,28 @@ palettes against its own.
 const THEME_PALETTES: Readonly<Record<"vestra" | "vestra-light", Readonly<Record<string, string>>>>;
 ```
 
+Example: Check in a test that a colour stays readable in both themes
+
+The test fails if the plugin's own highlight colour gets too close to
+the panel background of either palette. Plugins draw with `Theme` tokens
+in Slint and the player switches palettes; a colour the plugin picks
+itself does not switch, so a test compares it with each palette's values
+(hex strings, `#rrggbb`).
+```ts
+import assert from "node:assert/strict";
+import { THEME_PALETTES } from "@vestra-player/sdk/testing";
+
+const highlight = "#e07000"; // the plugin's own orange
+const luminance = (hex: string) => {
+  const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+  return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!; // rough, without gamma
+};
+for (const [name, palette] of Object.entries(THEME_PALETTES)) {
+  const gap = Math.abs(luminance(highlight) - luminance(palette["bg-panel"]!));
+  assert.ok(gap > 0.3, `${name}: highlight too close to bg-panel`);
+}
+```
+
 ### BINDING_INPUTS
 
 The names a binding (`CommandOptions.bindings`, `Bindings.set`) is made
@@ -8330,6 +11464,39 @@ const BINDING_INPUTS: Readonly<{
 }>;
 ```
 
+Example: Check in a test that the plugin's default keys are well formed
+
+The test fails on a binding the player would refuse with `invalid`, such
+as modifiers out of order or a misspelt key name. `isBinding` applies the
+same grammar as the player's parser: the part after the last `+` is the
+input, everything before it modifiers in the order of `modifiers`; an
+input is a listed name or one other printable character, and `Shift`
+never goes with a digit or such a character.
+```ts
+import assert from "node:assert/strict";
+import { BINDING_INPUTS } from "@vestra-player/sdk/testing";
+
+const { modifiers, letters, digits, functionKeys, named, mouse } = BINDING_INPUTS;
+const names = new Set([...letters, ...functionKeys, ...named, ...mouse]);
+function isBinding(binding: string): boolean {
+  // "Ctrl++" is not a binding: the + key is written "Plus".
+  const parts = binding.split("+");
+  const input = parts.pop()!;
+  const order = parts.map((m) => (modifiers as readonly string[]).indexOf(m));
+  // Each modifier known, at most once, in the listed order.
+  if (order.some((at, i) => at < 0 || (i > 0 && at <= order[i - 1]!)))
+    return false;
+  if (names.has(input)) return true; // letters are upper case: "A"
+  const typed = digits.includes(input) || /^[^\p{L}\p{N}\p{C}\s+]$/u.test(input);
+  // ">" rather than "Shift+.": the character already says Shift.
+  return typed && !parts.includes("Shift");
+}
+for (const binding of ["Ctrl+Shift+PageUp", "Alt+Mouse:WheelUp", ">"])
+  assert.ok(isBinding(binding), binding);
+for (const binding of ["Shift+Ctrl+A", "Ctrl+a", "Shift+."])
+  assert.ok(!isBinding(binding), binding);
+```
+
 ### OSD_LIMITS
 
 The player's limits on the on-screen display (Osd), counted on
@@ -8353,6 +11520,23 @@ const OSD_LIMITS: Readonly<{
 }>;
 ```
 
+Example: Keep a long list inside the information block's limits
+
+The block shows the first 32 rows of a list, each cut at 60 columns. The
+player counts the text as shown (after it is translated and formatted); a
+block over `panelLines` lines or `panelBytes` bytes is refused whole with
+`invalid`, reported to `Scope.onError` because `set` never throws, so
+the plugin trims the list itself (for very long non-ASCII rows, check the
+bytes too).
+```ts
+import { OSD_LIMITS } from "@vestra-player/sdk/testing";
+
+const panel = plugin.osd.panel();
+const lines = rows.slice(0, OSD_LIMITS.panelLines);
+// maxColumns cuts each longer line and ends it with "…".
+panel.set(lines.join("\n"), null, { maxColumns: 60 });
+```
+
 ### SESSION_STORAGE_LIMITS
 
 The player's limits on SessionStorage. A key outside them fails
@@ -8374,6 +11558,29 @@ const SESSION_STORAGE_LIMITS: Readonly<{
 }>;
 ```
 
+Example: Remember a position per URL without breaking the limits
+
+The plugin keeps the last position of each URL for this player session
+and skips a URL too long to be a key. Keys are counted in UTF-8 bytes, so
+the length is measured with `Buffer.byteLength`, not `length`; a `set`
+that would take the plugin's entries over 1 MiB rejects with `limit` and
+changes nothing, so the plugin clears the old entries and goes on.
+```ts
+import { SESSION_STORAGE_LIMITS } from "@vestra-player/sdk/testing";
+
+const session = plugin.storage.session;
+if (Buffer.byteLength(url) <= SESSION_STORAGE_LIMITS.keyBytes) {
+  try {
+    await session.set(url, position);
+  } catch (error) {
+    if ((error as PluginError).code !== "limit") throw error;
+    // Full: start over rather than lose the newest position.
+    for (const key of await session.keys()) await session.delete(key);
+    await session.set(url, position);
+  }
+}
+```
+
 ### SECRET_LIMITS
 
 The player's limits on Secrets. A name or value outside them
@@ -8391,6 +11598,32 @@ const SECRET_LIMITS: Readonly<{
 }>;
 ```
 
+Example: Store an API token only when it fits
+
+The plugin keeps a token the user pasted, or tells them it is empty or
+too long. Values are 1–1024 bytes counted in UTF-8, so the check uses
+`Buffer.byteLength`; `secrets.set` would refuse other values with
+`invalid`. The store itself can still refuse (`unsupported` without a
+system store, `unavailable` or `failed` when it denies access): only
+those codes get the "could not be saved" message, anything else (a
+missing `secrets` capability) is a bug and is thrown on.
+```ts
+import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
+
+if (!token || Buffer.byteLength(token) > SECRET_LIMITS.valueBytes) {
+  await plugin.osd.show("Paste a token of at most 1024 bytes.");
+} else {
+  try {
+    await plugin.secrets.set("api-token", token);
+  } catch (error) {
+    const { code } = error as PluginError;
+    if (!["unsupported", "unavailable", "failed"].includes(code)) throw error;
+    // No keychain or access denied: ask again next time.
+    await plugin.osd.show("The token could not be saved.");
+  }
+}
+```
+
 ### UI_VALUE_LIMITS
 
 The player's limits on one property value (a `PropValue` as written
@@ -8424,6 +11657,35 @@ const UI_VALUE_LIMITS: {
 };
 ```
 
+Example: Send a long playlist as a window of rows
+
+A list view shows any number of entries while each write stays small:
+the plugin sends only the rows around the scroll position plus the total,
+and the view reports where it scrolled to. After the `scrolled` handler
+returns, the SDK evaluates the `bind` function again and sends the new
+window. Each row object and each of its fields count as one value toward
+`values`, and so does the array holding them.
+```ts
+import { UI_VALUE_LIMITS } from "@vestra-player/sdk/testing";
+
+// 200 rows, or fewer if the limits were smaller: 2 fields per row make
+// 3 values (the row and its fields), plus 1 for the array.
+const size = Math.min(
+  200,
+  UI_VALUE_LIMITS.arrayRows,
+  Math.floor((UI_VALUE_LIMITS.values - 1) / 3),
+);
+let first = 0;
+list.bind(() => ({
+  total: entries.length,
+  rows: entries.slice(first, first + size),
+}));
+// The Slint view reports its first visible row; the window follows it.
+list.on("scrolled", (row: number) => {
+  first = Math.max(0, row - Math.floor(size / 2));
+});
+```
+
 ### IMAGE_LIMITS
 
 The player's runtime image limits (`host/src/ui_image.rs`): a file's
@@ -8474,6 +11736,29 @@ class HostError extends Error {
 }
 ```
 
+Example: Simulate the player refusing a clipboard write in a test
+
+The test proves the plugin sees a refused write as an error with code
+`failed`. `host.handle` replaces the test host's handler for one request
+method; the `HostError` it throws travels back like the player's own
+refusal, so the call rejects with that `code` and is not retried.
+`host.reset` puts the default handler back for later steps.
+```ts
+import assert from "node:assert/strict";
+import { HostError, startPlugin } from "@vestra-player/sdk/testing";
+import activate from "../main.ts";
+
+const { host, plugin, stop } = await startPlugin(activate, {
+  directory: new URL("..", import.meta.url),
+});
+host.handle("clipboard.writeText", () => {
+  throw new HostError("failed", "the system refused the write");
+});
+await assert.rejects(plugin.clipboard.writeText("x"), { code: "failed" });
+host.reset("clipboard.writeText"); // writes succeed again
+await stop();
+```
+
 ## Internal types the API refers to
 
 Not exported (do not import them); listed because public declarations use them.
@@ -9704,11 +12989,13 @@ export default async function activate(plugin: Plugin) {
   let mark: number | null = null;
 
   const window = plugin.windows.create("ui/bookmark.slint");
+  // Re-evaluated after every handler and player change; only changes are sent.
   window.bind(() => ({
     label: mark === null ? "No bookmark" : `Bookmark: ${mark.toFixed(1)} s`,
     canMark: player.state.position !== null,
     canJump: mark !== null && player.state.can.seek,
   }));
+  // The Slint callbacks `mark` and `jump` of ui/bookmark.slint.
   window.on("mark", () => (mark = player.state.position));
   window.on("jump", () => player.seek(mark!));
 
@@ -9716,7 +13003,7 @@ export default async function activate(plugin: Plugin) {
     id: "bookmark.open",
     path: ["@playback", "Bookmark…"],
     order: 270,
-    run: () => window.show(),
+    run: () => window.show(), // opens it, or brings back the open one
   });
 }
 ```
@@ -9872,6 +13159,7 @@ export default async function activate(plugin: Plugin) {
   const panel = plugin.panels.mount("sidebar", "ui/panel.slint", {
     title: "Example list",
   });
+  // Sent when the panel mounts, then whenever a value changes.
   panel.bind(() => ({ rows: items, selected }));
 
   const first = plugin.commands.add({
@@ -9889,7 +13177,9 @@ export default async function activate(plugin: Plugin) {
     },
   });
 
+  // Callbacks of the bridge global; `bind` above sends the new selection.
   panel.on("select", (index: number) => (selected = index));
+  // x and y: the pointer in window pixels, from the Slint file.
   panel.on("contextMenu", (x: number, y: number) =>
     panel.showMenu([first, null, remove], { x, y }),
   );
@@ -10400,6 +13690,7 @@ import type { Plugin } from "@vestra-player/sdk";
 
 /** A tool window that shows a Markdown document. */
 export default async function activate(plugin: Plugin) {
+  // Relative links and images in sample.md resolve against this folder.
   const directory = fileURLToPath(new URL(".", import.meta.url));
   const window = plugin.windows.create("ui/document.slint");
   plugin.commands.add({
@@ -10407,6 +13698,7 @@ export default async function activate(plugin: Plugin) {
     path: ["Examples", "Markdown example…"],
     run: async () => {
       const text = readFileSync(new URL("sample.md", import.meta.url), "utf8");
+      // `doc` is the window's [MarkdownBlock] property, drawn by MarkdownView.
       window.set({ doc: await plugin.ui.markdown(text, { base: directory }) });
       await window.show();
     },