@vestra-player/sdk 1.5.31 → 1.5.34

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.31: full reference
+# @vestra-player/sdk 1.5.34: 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.
 
@@ -740,7 +740,7 @@ plugin.video.view() returns the VideoView: aspect override, fit (keep with bars,
 
 plugin.video.render() returns the RenderOptions of the GPU renderer: HDR to SDR tone mapping and the display's brightness, user shaders (`.glsl` files) and motion interpolation. Like the display layer they act at display time only, have one owner (independent of the display layer's owner) and merge writes.
 
-- **Only the GPU renderer has them.** Under software rendering every `set` fails with `unsupported`; see Reference: platforms for where the player renders on the GPU. Treat `unsupported` as "hide these settings", not as an error.
+- **Only the GPU renderer has them.** Under software rendering every `set` fails with `unsupported`; see Reference: platforms for where the player renders on the GPU. Treat `unsupported` as "hide these settings", not as an error. To know before creating the handle, read rendering from `plugin.app.system()` (player 0.5.12, no capability): `"gpu"` or `"software"`.
 - A shader that does not compile is reported later: the status first becomes `applied`, then `failed` with code `failed` and the compiler's first error line once mpv first uses the shader.
 
 ## Concept: Windows, panels, settings pages, dialogs and the OSD
@@ -1134,7 +1134,7 @@ bar.on("forward30", () => plugin.host.run("seek-forward", { seconds: 30 })); //
 
 #### Next and previous
 
-The player's Next and Previous items, keys and buttons ask the **sequence provider**, one plugin at a time, first come first served. The built-in playlist registers as provider when it starts, so a plugin with its own list becomes the provider only while no other plugin holds it (for example with the playlist disabled). Any plugin can ask the provider with `player.next()` and `player.previous()`:
+The player's Next and Previous items, keys and buttons ask the **sequence provider**, one plugin at a time, first come first served. The built-in playlist registers as provider when it starts and a built-in plugin cannot be disabled, so in practice another plugin's `provideSequence` is refused (`sequence-taken`); only a development load that replaces the playlist under its id gets it. Any plugin can ask the provider with `player.next()` and `player.previous()`:
 
 ```ts
 declare const items: string[];
@@ -1229,6 +1229,85 @@ Names are 1–64 of `a-z 0-9 . _ -`, values 1–1024 bytes, at most 256 names. H
 
 For anything larger (a cache, downloaded files), write under `plugin.dataDirectory` with Node's `fs`. The player deletes the directory only when the plugin is uninstalled together with its data (`packages.uninstall` with `removeData`).
 
+## How-to: Load subtitles from a plugin
+
+**Goal:** your plugin finds subtitles for the playing file (on disk, on a website, by converting another format), adds them as a track, selects them, and optionally styles them.
+
+#### Capabilities
+
+```json
+{
+  "capabilities": ["subtitles.read", "subtitles.control", "events"]
+}
+```
+
+`subtitles.read` reads the tracks and the selection; `subtitles.control` changes them (and needs `subtitles.read` too, because every change reads the current selection first); `events` makes the SDK read `plugin.subtitles.state` again when the source or its phase changes. The player has no subtitle event: a selection the user or another plugin changes shows only after `refresh()`.
+
+#### Read the tracks
+
+`plugin.subtitles.state` is `null` until first read; `refresh()` reads it from the player. Each track has an `id` (compare tracks by id), a `kind` (`embedded` in the file or `external`, loaded from a file), a `title` and a `language`.
+
+```ts
+const state = plugin.subtitles.state ?? (await plugin.subtitles.refresh());
+for (const track of state.tracks)
+  console.log(track.id, track.kind, track.language ?? "?", track.title);
+// The primary and the secondary subtitle; null when off.
+console.log(state.selected?.id, state.secondary?.id);
+```
+
+#### Select a track, and handle `stale`
+
+Without options a change reads the newest state itself and applies to it, so it almost never fails. Embedded tracks are chosen by number, though: a `select` after another file opened would pick that file's track with the same number. Pass the state you looked at as `ifCurrent`; then the change fails with `stale`, and does nothing, when the user picked another track or another file opened in between:
+
+```ts
+const state = await plugin.subtitles.refresh();
+const english = state.tracks.find((track) => track.language === "en");
+if (english)
+  await plugin.subtitles.select(english, { ifCurrent: state }).catch((error: PluginError) => {
+    if (error.code !== "stale") throw error; // the user changed it meanwhile
+  });
+```
+
+`select(track, { role: "secondary" })` sets the second line shown together with the primary one (a text track other than the primary); `select(null)` turns a role off. A new source clears the secondary subtitle.
+
+#### Upload a file
+
+`load` takes the file's bytes: UTF-8 SRT, or ASS/SSA with `format: "ass"`, at most 2 MiB (SRT up to 10,000 cues, ASS up to 20,000 `Dialogue:` lines). Convert other formats (WebVTT, SAMI) to SRT first. The player adds an `external` track to the current source only, selects it unless `select: "none"`, and resolves with the track once the upload is committed. A plugin has at most 4 such tracks on a source at once and loads at most 16 files into it (removed ones count); past that `load` fails with `busy` (Limits).
+
+```ts
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+declare const path: string;
+// ---cut---
+const bytes = await readFile(path);
+const track = await plugin.subtitles.load(bytes, {
+  format: path.endsWith(".ass") ? "ass" : "srt",
+  title: basename(path), // data: shown as it is
+  select: "primary",
+  signal: AbortSignal.timeout(30_000), // discards the upload if not committed in time
+});
+await plugin.osd.show("Loaded {}", [track.title]);
+```
+
+A title that mixes words with data is a text value the player translates: `title: plugin.i18n.text("{} · {}", [plugin.i18n.text("Downloaded"), name])`. `remove(track)` takes away a track this plugin loaded; the next source removes it anyway.
+
+#### Style the subtitles
+
+`setStyle` sets this plugin's style layer: font (one of `state.fonts`), size at the 1080p reference height, colour, outline, margin, timing offset, box. Each plugin has one layer and its newest call replaces it. When several plugins set a layer, the player shows the one whose **manifest id sorts last**, whatever the order of the calls; `setStyle(null)` takes yours off.
+
+```ts
+const { fonts } = await plugin.subtitles.refresh();
+if (fonts.length)
+  await plugin.subtitles.setStyle({
+    fontId: fonts[0]!.id,
+    fontSize: 40,
+    color: "white",
+    outline: 2,
+    marginPercent: 5,
+    offsetMs: 0, // positive shows them later
+  });
+```
+
 ## How-to: Keep a slider responsive while dragging
 
 **Goal:** a slider in your window drives something live (a video filter, the volume, a preview), the effect follows the pointer while the user drags, and nothing lags behind or queues up.
@@ -2488,6 +2567,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.3 | Scrub.seek |
 | 0.5.5 | SessionStorage |
 | 0.5.10 | CommandButton, CommandOptions.button |
+| 0.5.12 | SystemInfo.rendering |
 
 The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
 
@@ -2645,6 +2725,21 @@ plugin.storage.session (player 0.5.5). A key out of its rule, or a value that is
 | `SESSION_STORAGE_LIMITS.bytes` | 1048576 (1 MiB) | Bytes one plugin may hold at the same time: for every key, its UTF-8 bytes, its value written as compact JSON (`JSON.stringify(value)`) and `entryBytes`. |
 | `SESSION_STORAGE_LIMITS.entryBytes` | 128 | What each key costs on top of its text and value (128): the player's own bookkeeping, so that many tiny entries stay within `bytes` of memory. |
 
+#### Subtitle files
+
+Subtitles.load uploads a file as a track of the current source. A file over `fileBytes` fails with `invalid`; every other limit fails with `busy` and nothing is loaded. The counts are per source, so another file starts from zero. Removing a track frees its place among the tracks and their bytes, but a load stays counted until the source changes.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `SUBTITLE_LIMITS.fileBytes` | 2097152 (2 MiB) | UTF-8 bytes of one file; a larger one fails with `invalid`. |
+| `SUBTITLE_LIMITS.tracksPerPlugin` | 4 | Tracks one plugin has loaded into the current source at the same time. |
+| `SUBTITLE_LIMITS.tracks` | 16 | Loaded tracks of every plugin in the current source at the same time. |
+| `SUBTITLE_LIMITS.totalBytes` | 16777216 (16 MiB) | Bytes of the loaded tracks of every plugin in the current source together. |
+| `SUBTITLE_LIMITS.loadsPerPlugin` | 16 | Loads by one plugin into the current source, removed tracks included. |
+| `SUBTITLE_LIMITS.loads` | 128 | Loads by every plugin into the current source, removed tracks included. |
+| `SUBTITLE_LIMITS.uploadsPerPlugin` | 2 | Loads of one plugin in progress at the same time. |
+| `SUBTITLE_LIMITS.uploads` | 8 | Loads of every plugin in progress at the same time. |
+
 #### Messages
 
 Every request a plugin sends travels as one protocol line. The plugin's side refuses a longer one with code `limit` before sending it; property values meet their own limits first.
@@ -3165,7 +3260,7 @@ A plugin uses the same API on macOS and Windows; the player does the system-spec
 | DropModifiers | The pointer and ⌥ ⇧ ⌘ (`cmd` is ⌘). | The pointer and Alt, Shift, Ctrl (`cmd` is Ctrl). |
 | plugin.system (open, reveal) | Opened by the system; revealing several files selects all of them in one Finder window. | Opened by the shell; one Explorer window per folder. |
 | plugin.secrets | The login keychain. | The Credential Manager. |
-| App.system() | Version, build, model and displays. | Version, build, model and displays. |
+| App.system() | Version, build, model and displays; `rendering` is `"gpu"`, or `"software"` after a fallback (a window that cannot show GPU frames). | Version, build, model and displays; `rendering` is `"software"`. |
 | Snapshots and exports (MediaCapture) | Available. | Available; needs FFmpeg 6.1 or newer. |
 | Generated streams (Player.openStream) | A Unix socket. | Loopback TCP with a token. |
 | Rendering | On the GPU (OpenGL), with hardware decoding. | In software, with hardware decoding copied back (`d3d11va-copy` and similar). |
@@ -3494,9 +3589,32 @@ flushes, a running `tools.run` process is killed and a listener is
 unsubscribed. A Media is the exception: disposing its scope does
 **not** close the media; call Media.close for that.
 
+Every handle a plugin creates is a `Disposable` owned by the scope that
+created it; disposing the scope (or stopping the plugin) disposes them in
+reverse creation order, so a plugin rarely calls `dispose` itself.
+
+- @capability None of its own: that of the handle.
+
 ```ts
 interface Disposable {
-  /** Release the resource. Resolves once the player confirmed the release (or immediately for purely local resources). Never rejects. */
+  /**
+   * Release the resource. Resolves once the player confirmed the release (or immediately for purely local resources). Never rejects.
+   * @capability None of its own: that of the handle.
+   * @throws Never.
+   * @example Remove a command when its feature is turned off
+   * A "Turn feature off" item removes the feature's own menu item at once,
+   * before the plugin stops. `dispose` takes the command out of the menu and
+   * the binding table and resolves once the player confirmed it; the id can
+   * be added again later.
+   * ```ts
+   * const extra = plugin.commands.add({ id: "extra", path: ["Tools", "Extra"], run() {} });
+   * plugin.commands.add({
+   *   id: "extra-off",
+   *   path: ["Tools", "Turn extra off"],
+   *   run: () => extra.dispose(), // never rejects
+   * });
+   * ```
+   */
   dispose(): Promise<void>;
 }
 ```
@@ -3522,7 +3640,6 @@ change).
 | code | meaning |
 | --- | --- |
 | `stale` | A condition no longer held (the source or the subtitle selection changed); nothing was done. See Conditional. |
-| `staleDigest` | PackageCandidate.install: the package's files changed after it was validated; validate it again. |
 | `capability` | The manifest does not declare the capability the call needs. |
 | `invalid` | A bad argument (out of range, malformed, unknown id). |
 | `missing` | The target does not exist (an empty panel position, a missing file, an unknown command). |
@@ -3542,7 +3659,7 @@ change).
 | `backend-uncertain` | The player's backend blocked a filter stage; call `retry()`. |
 | `limit` | A player-wide limit was reached (for example the number of commands), a property value is over the limits of PropValue, or a request is longer than the player's 1 MiB message. |
 | `reserved` | Packages.validate, PackageCandidate.install: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
-| `versionMismatch` | The package needs a newer player (`minPlayerVersion`) or another `apiVersion`. |
+| `versionMismatch` | The package needs a newer player (`minPlayerVersion`). |
 | `ui-prepare` | The player could not prepare a mounted panel or a settings page (its Slint file does not compile, a bound property is not declared, or another plugin's panel holds the slot); `message` has the diagnostics. |
 | `ui` | The player could not apply a property to a tool window or a settings page, or could not build the Options window (a property the Slint file does not declare, a value of the wrong type); `message` has Slint's reason. Also reported to Scope.onError without a request: a callback whose arguments the player could not convert, a property it could not show again when it rebuilt a view (an image file removed since). |
 | `host` | Any other failure inside the player; `message` is the player's reason. |
@@ -3605,6 +3722,14 @@ Reading Scope.window, Scope.app, Scope.appearance
 `.theme`, Scope.ui, Scope.tools, Scope.storage and
 Scope.system needs none.
 
+Every module of the API (`commands`, `windows`, `player`…) is reachable
+from a scope, and every handle made through it belongs to it. A child
+scope from Scope.scope is the unit for features that come and
+go: dispose the child and everything it created is released, while the
+rest of the plugin keeps running.
+
+- @capability That of each module (see the modules).
+
 ```ts
 interface Scope extends Disposable {
   /** Menu commands and their default bindings (`commands`). */
@@ -3628,10 +3753,16 @@ interface Scope extends Disposable {
      */
     filter(id: string): VideoFilter;
     /**
-     * The display layer (needs `processing.video`). The first plugin to call it owns the layer; another plugin's view fails with `conflict` until the owner disposes or stops. A second call in the same plugin throws.
+     * The display layer (needs `processing.video`). The first plugin to call it owns the layer; another plugin's view fails with `conflict` until the owner disposes or stops.
+     * @throws capability (throws) The manifest does not declare `processing.video`.
+     * @throws Error without a code (throws) A second call in the same plugin while the first view is not disposed.
      */
     view(): VideoView;
-    /** The GPU renderer's options (needs `processing.video`), owned like the display layer. `failed` with `unsupported` under software rendering. */
+    /**
+     * The GPU renderer's options (needs `processing.video`), owned like the display layer. Under software rendering the handle is `failed` with `unsupported` after the player's first answer, and `onError` hears it.
+     * @throws capability (throws) The manifest does not declare `processing.video`.
+     * @throws Error without a code (throws) A second call in the same plugin while the first handle is not disposed.
+     */
     render(): RenderOptions;
   };
   /** Audio processing: this plugin's filter chain and delay (`processing.audio`, `playback.read` and `events`, as for VideoFilter). */
@@ -3685,17 +3816,57 @@ interface Scope extends Disposable {
   readonly i18n: I18n;
   /** Pages in the player's options window (`ui.settings`). */
   readonly settings: Settings;
-  /** A child scope; disposing it releases only what was created through it. The child is itself owned by this scope. */
+  /**
+   * A child scope; disposing it releases only what was created through it. The child is itself owned by this scope.
+   * @capability None.
+   * @example Tie a temporary window and its timer to one feature
+   * A "Live stats" feature opens a window and starts a timer; turning it off
+   * releases both together. Everything made through the child scope, and
+   * cleanups registered on it, go when the child is disposed; the parent
+   * scope is untouched.
+   * ```ts
+   * let live: Scope | null = null;
+   * plugin.commands.add({
+   *   id: "live-stats",
+   *   path: ["Tools", "Live stats"],
+   *   checked: () => live !== null,
+   *   run: async () => {
+   *     if (live) {
+   *       await live.dispose(); // closes the window, stops the timer
+   *       live = null;
+   *       return;
+   *     }
+   *     live = plugin.scope();
+   *     const window = live.windows.create("ui/stats.slint");
+   *     const timer = setInterval(() => live?.update(), 1000);
+   *     live.onDispose(() => clearInterval(timer));
+   *     await window.show();
+   *   },
+   * });
+   * ```
+   */
   scope(): Scope;
   /**
    * Adopt an existing handle: it is disposed together with this scope.
    * @param item - Any Disposable, for example a handle created through another scope.
    * @returns `item` itself, for chaining.
+   * @capability None.
+   * @example Dispose a handle from another scope together with this one
+   * A filter made through the root scope is withdrawn when a child feature
+   * ends. `add` hands an existing disposable to this scope, which then
+   * disposes it with its own handles; it returns the same handle for
+   * chaining.
+   * ```ts
+   * const feature = plugin.scope();
+   * const blur = feature.add(plugin.video.filter("blur")); // now ends with `feature`
+   * blur.set([{ kind: "gblur", sigma: 4, steps: 3 }]);
+   * ```
    */
   add<T extends Disposable>(item: T): T;
   /**
    * 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`).
+   * @capability None.
    * @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
@@ -3714,6 +3885,7 @@ 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).
+   * @capability None.
    * @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
@@ -3733,6 +3905,23 @@ interface Scope extends Disposable {
    * changing state from your own timers or between awaits of a long task.
    *
    * Several calls within one microtask are merged into one pass.
+   * @capability None.
+   * @example Show progress from a long task between awaits
+   * A progress label moves while a long download runs, not only when it
+   * ends. The SDK re-evaluates bound values after each handler and when its
+   * promise settles; state changed between the awaits of a long handler
+   * shows only after an explicit `update()`.
+   * ```ts
+   * let done = 0;
+   * window.bind(() => ({ progress: done }));
+   * window.on("start", async () => {
+   *   for (let part = 0; part < 10; part++) {
+   *     await downloadPart(part);
+   *     done = part + 1;
+   *     plugin.update(); // send `progress` now, not when the handler ends
+   *   }
+   * });
+   * ```
    */
   update(): void;
 }
@@ -3781,6 +3970,12 @@ root scope is disposed for local cleanup (timers, signals, sockets). A
 process that has not exited after 300 ms is killed. Media the plugin
 opened with Player.open keeps playing.
 
+The root scope: disposing it is what stopping the plugin does. Besides
+the modules of Scope, it carries the plugin's `id` and its
+`dataDirectory`.
+
+- @capability That of each module (see the modules).
+
 ```ts
 interface Plugin extends Scope {
   /** The manifest id, e.g. `"community.bookmark"`. */
@@ -5787,6 +5982,13 @@ interface DropHandler {
 
 `plugin.drops`: files dropped on the video area. Needs `ui.drop`.
 
+Files dropped on the video area go to providers by extension: each
+extension belongs to the provider registered for it first, and each
+provider gets one call with all of its paths. Files nobody takes are
+ignored. A panel with Panel.onDrop takes drops on itself first.
+
+- @capability ui.drop
+
 ```ts
 interface Drops {
   /**
@@ -5797,6 +5999,7 @@ interface Drops {
    * 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.
+   * @capability ui.drop
    * @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;
@@ -5822,6 +6025,25 @@ interface Drops {
 }
 ```
 
+Example: Collect dropped CHIP-8 programs
+
+`.ch8` files dropped on the player are added to the plugin's list. The
+provider claims the extension; the player calls `drop` with the dropped
+paths of that type, in the order the file manager gave them. Extensions
+go to the first provider: the built-in playlist claims every audio and
+video extension when it starts, and a built-in plugin cannot be disabled,
+so another plugin's provider for those never gets them (except a
+development load that replaces the playlist under its id).
+```ts
+const queue: string[] = [];
+plugin.drops.provide({
+  extensions: ["ch8"],
+  drop: ({ paths }) => {
+    queue.push(...paths); // only .ch8 files reach here
+  },
+});
+```
+
 ### ThemeId
 
 The player's palettes: `vestra`, the dark default, and `vestra-light`
@@ -6693,10 +6915,18 @@ interface TimelineMark {
 
 This plugin's own marks; disposing it removes them.
 
+This plugin's marks on the seek bar, from Timeline.layer. `set`
+replaces the whole layer and never throws: the newest write wins, and a
+refused one is reported to `onError`. Disposing the layer, its scope or
+stopping the plugin removes the marks.
+
+- @capability timeline.marks
+
 ```ts
 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.
+   * @capability timeline.marks
    * @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`
@@ -6721,22 +6951,76 @@ interface TimelineLayer extends Disposable {
 }
 ```
 
+Example: Clear the plugin's marks
+
+The plugin's marks disappear from the seek bar while it keeps its
+layer for later. An empty list clears the layer; other plugins' marks
+stay.
+```ts
+plugin.timeline.layer().set([]);
+```
+
 ### Timeline
 
 `plugin.timeline`: marks on the seek bar. Every plugin publishes one
 layer; the player merges them. A new source clears every layer.
 
+Marks on the player's seek bar: chapters, bookmarks, loop points. Each
+plugin publishes one layer with Timeline.layer; the player merges
+the layers by time and shows them. A new source clears every layer, so a
+plugin publishes again for each file. `marks` is the merged list, which
+any plugin can read.
+
+- @capability `timeline.marks` to publish; `playback.read` to read; `events` to follow changes.
+
 ```ts
 interface Timeline {
   /** Every layer merged, by time (`playback.read`). Empty on a new source. */
   readonly marks: readonly TimelineMark[];
-  /** The merged list changed (needs `events`; at most every 100 ms). */
+  /**
+   * The merged list changed (needs `events`; at most every 100 ms).
+   * @capability events and playback.read
+   * @example Follow the marks as they change
+   * A panel lists the seek bar's marks and updates when any plugin publishes
+   * or a new file clears them. The listener gets the merged list, at most
+   * every 100 ms.
+   * ```ts
+   * plugin.timeline.onChange((marks) => {
+   *   console.log(marks.map((mark) => `${mark.time}s ${mark.title ?? mark.kind}`));
+   * });
+   * ```
+   */
   onChange(listener: (marks: readonly TimelineMark[]) => void): Disposable;
-  /** This plugin's layer (`timeline.marks`); a second call throws. */
+  /**
+   * This plugin's layer (`timeline.marks`); a second call throws.
+   * @capability timeline.marks
+   * @example Publish this plugin's marks
+   * The plugin gets its one layer and puts two chapter marks on the seek
+   * bar. Calling `layer()` again while the first layer is not disposed
+   * throws; disposing the layer removes the
+   * marks.
+   * ```ts
+   * const layer = plugin.timeline.layer();
+   * layer.set([
+   *   { time: 0, kind: "chapter", title: "Intro" },
+   *   { time: 95, kind: "chapter", title: "Part 1" }, // seconds
+   * ]);
+   * ```
+   */
   layer(): TimelineLayer;
 }
 ```
 
+Example: Count the chapter marks other plugins published
+
+The plugin reads how many chapter marks the seek bar shows, whoever
+published them. `marks` is the merged list of every layer, sorted by
+time, with each mark's `plugin`.
+```ts
+const chapters = plugin.timeline.marks.filter((mark) => mark.kind === "chapter");
+await plugin.osd.show("{} chapters", [chapters.length]);
+```
+
 ### WindowState
 
 The main window as `plugin.window.state` reports it (logical points).
@@ -6772,11 +7056,28 @@ With `events`, `state` follows the window from the first read or
 `onChange`; without it, it updates only at start and after this plugin's
 `setVideoArea`.
 
+`plugin.window` is the player's main window: its size, fullscreen,
+picture-in-picture and the video area. Reading it needs no capability;
+changing it needs `window.control`. Changes that last only while the
+plugin runs (always on top, pointer auto-hide) revert when it stops.
+
+- @capability None to read; window.control to change; events to follow outside changes.
+
 ```ts
 interface MainWindow {
   /** Latest state; zero video area without a native window. */
   readonly state: WindowState;
-  /** The window state changed (needs `events` for outside changes). */
+  /**
+   * The window state changed (needs `events` for outside changes).
+   * @capability events (for outside changes)
+   * @example Fit a panel to fullscreen
+   * The plugin's panel uses larger text while the player is fullscreen. The
+   * listener runs after the SDK updated `state` from the player's events
+   * (with `events`; without it only after this plugin's own changes).
+   * ```ts
+   * plugin.window.onChange((state) => bar.set({ large: state.fullscreen }));
+   * ```
+   */
   onChange(listener: (state: WindowState) => void): Disposable;
   /**
    * Resize the window so the video column is `width`×`height` (the bottom bar
@@ -6788,6 +7089,18 @@ interface MainWindow {
    * Sizes are 1–16384 logical points; the minimum video area is 318×120.
    * The visible area excludes the menu bar and Dock on macOS; on Windows it
    * is the whole display. `unavailable` without a user interface too.
+   * @capability window.control
+   * @throws unavailable (rejects) Fullscreen, or no user interface.
+   * @throws invalid (rejects) A size outside 1–16384 logical points.
+   * @throws capability (rejects) The manifest does not declare `window.control`.
+   * @example Make the video area 1280×720 points
+   * The window resizes so that the video column is 1280×720 logical points,
+   * the bars and a docked sidebar added around it. A request that does not
+   * fit the screen is scaled down keeping the aspect, and `clamped` says so.
+   * ```ts
+   * const applied = await plugin.window.setVideoArea({ width: 1280, height: 720 });
+   * if (applied.clamped) await plugin.osd.show("{}×{}", [applied.width, applied.height]);
+   * ```
    */
   setVideoArea(size: {
     width: number;
@@ -6800,10 +7113,42 @@ interface MainWindow {
     /** The request was scaled down or raised to fit. */
     clamped: boolean;
   }>;
-  /** Float the player's windows above other applications. Newest call wins; reverts when this plugin stops. `unavailable` without a user interface. */
+  /**
+   * Float the player's windows above other applications. Newest call wins; reverts when this plugin stops. `unavailable` without a user interface.
+   * @capability window.control
+   * @throws unavailable (rejects) No user interface.
+   * @throws invalid (rejects) `onTop` is not a boolean.
+   * @throws capability (rejects) The manifest does not declare `window.control`.
+   * @example Keep the player above other windows
+   * The player's windows (tool windows too) float above other applications
+   * while the plugin's "Always on top" item is checked. The newest call of
+   * any plugin wins, and the setting reverts when this plugin stops.
+   * ```ts
+   * let onTop = false;
+   * plugin.commands.add({
+   *   id: "on-top",
+   *   path: ["@screen", "Always on top"],
+   *   checked: () => onTop,
+   *   run: async () => {
+   *     onTop = !onTop;
+   *     await plugin.window.setAlwaysOnTop(onTop); // reverts when this plugin stops
+   *   },
+   * });
+   * ```
+   */
   setAlwaysOnTop(onTop: boolean): Promise<void>;
   /**
    * `"playing"`: hide the pointer over the video after 3 idle seconds while playing, in a window too (not only fullscreen). Newest call wins; reverts to `"fullscreen"` when this plugin stops.
+   * @capability window.control
+   * @throws invalid (rejects) A mode other than `"fullscreen"` or `"playing"`.
+   * @throws capability (rejects) The manifest does not declare `window.control`.
+   * @example Hide the pointer over playing video in a window too
+   * The pointer disappears after 3 idle seconds over playing video, not only
+   * in fullscreen. The newest call wins; when this plugin stops the player
+   * goes back to hiding it in fullscreen only.
+   * ```ts
+   * await plugin.window.setCursorAutoHide("playing");
+   * ```
    */
   setCursorAutoHide(mode: "fullscreen" | "playing"): Promise<void>;
   /**
@@ -6818,6 +7163,13 @@ interface MainWindow {
    *
    * Where it is unsupported (Windows, Linux), `setVideoArea` plus
    * `setAlwaysOnTop` make a reasonable "mini player" fallback.
+   * @capability window.control
+   * @throws unsupported (rejects) The system has no picture-in-picture (`supported` is false).
+   * @throws unavailable (rejects) No video, or no user interface.
+   * @throws invalid (rejects) `on` is not a boolean.
+   * @throws busy (rejects) The previous call is still switching.
+   * @throws failed (rejects) The system refused.
+   * @throws capability (rejects) The manifest does not declare `window.control`.
    * @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
@@ -6881,9 +7233,29 @@ interface AppInfo {
 `plugin.app`: the fixed facts plus the system, read on request. No
 capability.
 
+`plugin.app` holds facts fixed for the player's run (its version, build,
+library versions) and reads the system's on request: `system()` reads
+the displays at each call; the operating system's name and version are
+worked out once, at the first call, and reused.
+
+- @capability None.
+
 ```ts
 interface App extends AppInfo {
-  /** The operating system and the displays, read when called (displays come and go). No capability. CPU and memory: Node's `os` module. */
+  /**
+   * The operating system, the displays and the renderer, read when called (displays come and go; the renderer can fall back from GPU to software once). No capability. CPU and memory: Node's `os` module.
+   * @capability None.
+   * @throws busy (rejects) The player could not start the request (no thread available).
+   * @example Choose a size for the primary display
+   * The plugin sizes its picture for the primary display. `system()` asks
+   * the player; `displays` lists the displays present now, the primary one
+   * first (empty without a user interface).
+   * ```ts
+   * const { displays } = await plugin.app.system();
+   * const primary = displays[0];
+   * if (primary) console.log(primary.width, primary.height);
+   * ```
+   */
   system(): Promise<SystemInfo>;
 }
 ```
@@ -6920,6 +7292,42 @@ interface SystemInfo {
   readonly arch: string;
   /** Primary display first; empty without a user interface. */
   readonly displays: readonly DisplayInfo[];
+  /**
+   * Which renderer draws the video now: `"gpu"` (the GPU renderer, so
+   * render options apply) or `"software"` (they
+   * fail with `unsupported`). Read at each call. It changes at most once
+   * while the player runs, from `"gpu"` to `"software"` when a window
+   * cannot show GPU frames; the owner of the render options hears that
+   * switch through RenderOptions.onStatus.
+   *
+   * Absent (`undefined`) on players before 0.5.12, which do not report it:
+   * the renderer is then unknown, not software.
+   *
+   * Today the player renders on the GPU on macOS and in software on
+   * Windows, Linux and without a user interface (see
+   * Platforms); test this field
+   * rather than SystemInfo.os.
+   * @player 0.5.12; older players leave it out (declare `"minPlayerVersion": "0.5.12"` when the plugin relies on it).
+   * @example Offer the HDR menu only where render options work
+   * The plugin adds its HDR command only when the player renders on the
+   * GPU, instead of creating the render options just to find out from a
+   * failed status. `system()` asks the player, which reports the renderer
+   * drawing at that moment; no capability is needed to ask. A player before
+   * 0.5.12 leaves the field out, so the test is for `"gpu"` exactly (an
+   * older player gets no HDR command).
+   * ```ts
+   * const { rendering } = await plugin.app.system();
+   * if (rendering === "gpu") {
+   *   const render = plugin.video.render(); // one handle, kept
+   *   plugin.commands.add({
+   *     id: "hdr",
+   *     path: ["@video", "HDR Tone Mapping"],
+   *     run: () => render.set({ toneMapping: "bt.2390", targetPeak: 250 }),
+   *   });
+   * }
+   * ```
+   */
+  readonly rendering?: "gpu" | "software";
 }
 ```
 
@@ -8611,6 +9019,14 @@ one request is in flight at a time and only the newest value is sent.
 Values out of range fail with `invalid` (see VideoNode). The
 same chain applies to processed snapshots and exports.
 
+Members: `set(nodes)` records the desired chain (last write wins) and
+sends it, one request at a time and only the newest; `status` and
+`onStatus` report `waiting`, `applying`, `applied` or `failed`; `retry`
+applies the current value again; `dispose` withdraws the chain. `set`
+never throws: a refused chain shows as `failed` in `status`.
+
+- @capability processing.video, playback.read and events
+
 ```ts
 type VideoFilter = Filter<VideoNode[]>;
 ```
@@ -8638,6 +9054,12 @@ VideoFilter.
 `delayMs` is −10000–10000 in multiples of 10; the positive and the
 negative delays of all plugins each add up to at most 10000.
 
+The same members and rules as VideoFilter: `set` records the
+desired value and never throws, `status` and `onStatus` report the
+result, `retry` applies it again, `dispose` withdraws it.
+
+- @capability processing.audio, playback.read and events
+
 ```ts
 type AudioFilter = Filter<{
   /** The audio chain; `[]` for none. */
@@ -8688,13 +9110,46 @@ needed); disposing or stopping the owner restores the defaults.
 Out-of-range values or unknown fields fail with `invalid` without
 sending anything.
 
+Not part of snapshots or exports: it changes how the picture sits in the
+video area, not the picture. `set` merges into the current settings and
+never throws: an out-of-range value or unknown field shows as `failed`
+(`invalid`) in `status` and is reported to `onError`, without sending
+anything.
+
+- @capability processing.video, playback.read and events (like VideoFilter)
+
 ```ts
 interface VideoView extends Disposable {
-  /** Merged into the current settings; last write wins. */
+  /**
+   * Merged into the current settings; last write wins.
+   * @capability processing.video
+   * @example Stretch a 4:3 video to fill the window
+   * A 4:3 video fills a 16:9 window, distorted, as the user asked. Each
+   * `set` merges the given fields into this plugin's view settings; the
+   * newest write wins, and the settings stay for later files until the
+   * plugin disposes the view or stops.
+   * ```ts
+   * plugin.video.view().set({ fit: "stretch" });
+   * ```
+   */
   set(value: Partial<ViewSettings>): void;
   /** Current status (the same four states as filters). */
   readonly status: FilterStatus;
-  /** The status changed. */
+  /**
+   * The status changed.
+   * @capability processing.video
+   * @example Tell the user another plugin owns the view
+   * When another plugin already controls the display layer, the OSD says
+   * so. The first plugin to call `view()` owns it; this plugin's handle
+   * then reports `failed` with `conflict`, and tries again on its next `set`.
+   * ```ts
+   * const view = plugin.video.view();
+   * view.onStatus((status) => {
+   *   if (status.state === "failed" && status.error.code === "conflict")
+   *     void plugin.osd.show("Another plugin controls the picture size");
+   * });
+   * ```
+   */
   onStatus(listener: (status: FilterStatus) => void): Disposable;
 }
 ```
@@ -8704,7 +9159,7 @@ 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.
+which stay across sources until the plugin disposes the view or stops.
 ```ts
 const view = plugin.video.view();
 view.set({ fit: "fill" });
@@ -8739,16 +9194,50 @@ independent handles.
 
 Platforms: only macOS renders on the GPU. Under software rendering
 (Windows, Linux, headless, fallback) every `set` fails with
-`unsupported`. macOS OpenGL 4.1 has no compute shaders, so `peakDetect`
-is accepted but has no effect; output is always SDR.
+`unsupported`; SystemInfo.rendering tells which renderer draws
+without creating the handle. macOS OpenGL 4.1 has no
+compute shaders, so `peakDetect` is accepted but has no effect; output
+is always SDR.
+
+GPU renderer options (tone mapping, peak detection, shaders,
+interpolation). Only the GPU renderer has them, which today means macOS;
+under software rendering the handle is `failed` with `unsupported` after
+the player's first answer to `render()` (reported to `onError` too), and so is
+every `set`. Single owner, like VideoView. `set` never throws; the
+result shows in `status`.
+
+- @capability processing.video, playback.read and events (like VideoFilter)
 
 ```ts
 interface RenderOptions extends Disposable {
-  /** Merged into the current settings; last write wins. */
+  /**
+   * Merged into the current settings; last write wins.
+   * @capability processing.video
+   * @example Turn on motion interpolation
+   * Motion becomes smoother on the GPU renderer. `set` merges the field into
+   * the plugin's render options; under software rendering the status turns
+   * `failed` with `unsupported` instead.
+   * ```ts
+   * plugin.video.render().set({ interpolation: true });
+   * ```
+   */
   set(value: Partial<RenderSettings>): void;
   /** `failed` with `unsupported` while the player renders in software; `failed` with `failed` when mpv cannot compile a shader (pushed later). */
   readonly status: FilterStatus;
-  /** The status changed (including later pushes such as shader compile errors). */
+  /**
+   * The status changed (including later pushes such as shader compile errors).
+   * @capability processing.video
+   * @example Report a shader that does not compile
+   * The OSD shows mpv's message when a shader the plugin set fails to
+   * compile. The player pushes that failure after the `set` was accepted, so
+   * it arrives through `onStatus`, not as a rejected call.
+   * ```ts
+   * const render = plugin.video.render();
+   * render.onStatus((status) => {
+   *   if (status.state === "failed") void plugin.osd.show("Render: {}", [status.error.message]);
+   * });
+   * ```
+   */
   onStatus(listener: (status: FilterStatus) => void): Disposable;
 }
 ```
@@ -8850,16 +9339,79 @@ interface SubtitleConditional {
 `subtitles.read`; changes need `subtitles.control` and also
 `subtitles.read`, since they read the current selection first.
 
+The subtitle tracks of the current source, the primary and secondary
+selection, uploaded files and the style. `state` is the SDK's snapshot of
+the player's subtitle state (`null` until first read). The player has no
+subtitle event: the SDK reads the state again when the source, its phase
+or the backend changes (with `events`) and after this plugin's own
+changes, so a selection the user or another plugin changed shows only
+after `refresh()`. A change without `ifCurrent` reads the state first
+and applies to it; pass `ifCurrent` to make it fail with `stale` when the
+selection changed since that state. Each change is one operation the
+player confirms; `select`, `remove` and `setStyle` resolve with the new
+state, `load` with the new track.
+
+- @capability `subtitles.read` to read; `subtitles.control` and `subtitles.read` to change; `events` to re-read on source changes.
+
 ```ts
 interface Subtitles {
   /** `null` until first read. */
   readonly state: SubtitlesState | null;
-  /** The subtitle state changed. */
+  /**
+   * The subtitle state changed.
+   * @capability events and subtitles.read
+   * @example Show the subtitle language after a new file opens
+   * When a new file starts, the OSD names the language of its primary
+   * subtitle. The SDK reads the subtitle state again when the source or its
+   * phase changes (there is no subtitle event, so a selection changed in the
+   * player shows only after `refresh()`) and then calls the listener;
+   * `selected` is `null` when subtitles are off.
+   * ```ts
+   * plugin.subtitles.onChange((state) => {
+   *   // A track's language is null when the file does not say.
+   *   void plugin.osd.show("Subtitles: {}", [state.selected?.language ?? "off"]);
+   * });
+   * ```
+   */
   onChange(listener: (state: SubtitlesState) => void): Disposable;
-  /** Read the state from the player now. */
+  /**
+   * Read the state from the player now.
+   * @capability subtitles.read
+   * @throws capability (rejects) The manifest does not declare `subtitles.read`.
+   * @example Count the subtitle tracks of the file
+   * The plugin reads how many subtitle tracks the file has before building a
+   * menu. `refresh` asks the player and resolves with the current state, also
+   * without `events`; `state` holds it afterwards.
+   * ```ts
+   * const { tracks } = await plugin.subtitles.refresh();
+   * await plugin.osd.show("{} subtitle tracks", [tracks.length]);
+   * ```
+   */
   refresh(): Promise<SubtitlesState>;
   /**
    * `role: "secondary"` sets the secondary subtitle: a text track that is not the primary one (`invalid` otherwise). A new source clears it. `track: null` turns the role off.
+   * @capability subtitles.control and subtitles.read
+   * @throws stale (rejects) With `ifCurrent`: the source or the subtitle selection changed since that state.
+   * @throws invalid (rejects) An unknown track; as secondary, a bitmap track or the primary one; as primary, the current secondary.
+   * @throws missing (rejects) The track is not in the current source.
+   * @throws unavailable (rejects) Nothing loaded, or the source is still loading or not yet confirmed.
+   * @throws busy (rejects) Too many subtitle operations at once.
+   * @throws capability (rejects) The manifest does not declare `subtitles.control` and `subtitles.read`.
+   * @example Turn on the first English subtitle
+   * The first English track becomes the primary subtitle, but only in the
+   * file the plugin looked at. Embedded tracks are chosen by number, so
+   * without `ifCurrent` a select after another file opened would pick that
+   * file's track with the same number; with `ifCurrent: state` it fails with
+   * `stale` instead. Without `ifCurrent`, `select` reads the newest state
+   * itself and almost never fails with `stale`.
+   * ```ts
+   * const state = await plugin.subtitles.refresh();
+   * const english = state.tracks.find((track) => track.language === "en");
+   * if (english)
+   *   await plugin.subtitles.select(english, { ifCurrent: state }).catch((error: PluginError) => {
+   *     if (error.code !== "stale") throw error; // another file or selection now
+   *   });
+   * ```
    */
   select(track: SubtitleTrack | null, options?: SubtitleConditional & {
     role?: "primary" | "secondary";
@@ -8875,7 +9427,29 @@ interface Subtitles {
    *
    * Limits: SRT ≤ 2 MiB and ≤ 10,000 cues; ASS ≤ 2 MiB with `[Script Info]`
    * and `[Events]` and 1–20,000 `Dialogue:` lines. Convert other formats
-   * (VTT, SAMI) to SRT first.
+   * (VTT, SAMI) to SRT first. Per source, a plugin has at most 4 loaded
+   * tracks at once and loads at most 16 files (removed ones count), and
+   * every plugin together at most 16 tracks; see `SUBTITLE_LIMITS` in
+   * `@vestra-player/sdk/testing`.
+   * @capability subtitles.control and subtitles.read
+   * @throws invalid (rejects) A bad `format` or `title`, or a file over the limits.
+   * @throws stale (rejects) With `ifCurrent`: the source changed since that state.
+   * @throws unavailable (rejects) Nothing loaded, or the source is still loading.
+   * @throws aborted (rejects) `signal` aborted before the commit (an `AbortError`); the upload is discarded.
+   * @throws busy (rejects) Too many subtitle operations at once, or a limit of `SUBTITLE_LIMITS` is reached (4 tracks of this plugin, 16 loads of this plugin or 16 tracks in the source, or another of its limits); nothing is loaded.
+   * @throws capability (rejects) The manifest does not declare `subtitles.control` and `subtitles.read`.
+   * @example Load a downloaded SRT and select it
+   * A subtitle file the plugin downloaded becomes a track of the current file
+   * and is selected. The plugin passes the file's bytes; the player parses
+   * them, adds an `external` track for this source only and resolves with
+   * it once the upload is committed.
+   * ```ts
+   * const response = await fetch(url);
+   * if (!response.ok) throw new Error(`subtitles: HTTP ${response.status}`);
+   * const bytes = new Uint8Array(await response.arrayBuffer());
+   * const track = await plugin.subtitles.load(bytes, { title: "Downloaded" }); // selected
+   * await plugin.osd.show("Loaded {}", [track.title]);
+   * ```
    */
   load(bytes: Uint8Array, options?: SubtitleConditional & {
     format?: "srt" | "ass";
@@ -8883,10 +9457,40 @@ interface Subtitles {
     select?: "primary" | "secondary" | "none";
     signal?: AbortSignal;
   }): Promise<SubtitleTrack>;
-  /** Remove a track this plugin loaded. */
+  /**
+   * Remove a track this plugin loaded.
+   * @capability subtitles.control and subtitles.read
+   * @throws invalid (rejects) The track was not loaded by this plugin.
+   * @throws stale (rejects) With `ifCurrent`: the source changed since that state.
+   * @throws unavailable (rejects) Nothing is loaded, or the source is still loading.
+   * @throws busy (rejects) Too many subtitle operations at once.
+   * @throws capability (rejects) The manifest does not declare `subtitles.control` and `subtitles.read`.
+   * @example Remove the subtitle the plugin loaded
+   * The plugin's downloaded subtitle disappears from the track list. A plugin
+   * can remove only tracks it loaded itself; a new source removes them
+   * anyway.
+   * ```ts
+   * await plugin.subtitles.remove(loaded);
+   * ```
+   */
   remove(track: SubtitleTrack, options?: SubtitleConditional): Promise<SubtitlesState>;
   /**
    * 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.
+   * @capability subtitles.control and subtitles.read
+   * @throws invalid (rejects) A field out of range.
+   * @throws unsupported (rejects) A font that is not in `state.fonts`, or a primary subtitle that is a bitmap track.
+   * @throws stale (rejects) With `ifCurrent`: the subtitle state changed since that state.
+   * @throws unavailable (rejects) Nothing is loaded, or the source is still loading.
+   * @throws busy (rejects) Too many subtitle operations at once.
+   * @throws capability (rejects) The manifest does not declare `subtitles.control` and `subtitles.read`.
+   * @example Take the plugin's style off again
+   * The plugin removes its style layer, so the subtitles go back to the
+   * player's default (or to another plugin's layer). `null` removes only this
+   * plugin's layer; the effective layer is the one whose manifest id sorts
+   * last among the plugins that still have one.
+   * ```ts
+   * await plugin.subtitles.setStyle(null);
+   * ```
    */
   setStyle(style: SubtitleStyle | null, options?: SubtitleConditional): Promise<SubtitlesState>;
 }
@@ -8937,6 +9541,14 @@ interface CaptureOptions extends Conditional {
 
 A frozen, immutable input for exports. Dispose to release it.
 
+A frozen input, from MediaCapture.capture: the source, the time
+and (processed) the effects and subtitle as they were. Exports read it in
+the player's offline worker, so one snapshot can be exported several
+times and playback is unaffected. Disposing it releases the player's
+copy; an export using it after that fails with `released`.
+
+- @capability media.read and media.control
+
 ```ts
 interface Snapshot extends Disposable {
   /** Without or with effects. */
@@ -8958,11 +9570,45 @@ interface Snapshot extends Disposable {
   } | null;
   /** The frozen processing revision (processed snapshots). */
   readonly processingRevision: number | null;
-  /** Start exporting; the job runs in the host's offline worker. One snapshot can be exported several times. */
+  /**
+   * Start exporting; the job runs in the host's offline worker. One snapshot can be exported several times.
+   * @capability media.read and media.control
+   * @throws released (rejects) The snapshot was already released.
+   * @throws invalid (rejects) Bad options (`quality` outside 1–100, a relative destination, a clip `end` not after the snapshot time or past the duration).
+   * @throws busy (rejects) This plugin runs 2 exports (or the player 8).
+   * @throws unavailable (rejects) No FFmpeg, or the export worker could not start.
+   * @throws capability (rejects) The manifest does not declare `media.read` and `media.control`.
+   * @example Export a 30-second clip
+   * A clip from the snapshot time to 30 seconds later is written as MP4.
+   * `export` resolves once the job is accepted; the job then runs in the
+   * player's offline worker, and `done` resolves with its terminal state,
+   * whose `outcome` has the destination or the error.
+   * ```ts
+   * const job = await snapshot.export({ format: "mp4", destination: "/tmp/clip.mp4", end: snapshot.time + 30 });
+   * const end = await job.done;
+   * if (end.status !== "completed") await plugin.osd.show("Export {}", [end.status]);
+   * ```
+   */
   export(options: ExportOptions): Promise<ExportJob>;
 }
 ```
 
+Example: Export one frame as PNG and as JPEG
+
+The same frozen frame is written twice, lossless and compressed. Each
+`export` starts a job of its own; the snapshot is released after both
+are done.
+```ts
+const snapshot = await plugin.media.capture();
+try {
+  const png = await snapshot.export({ format: "png", destination: "/tmp/frame.png" });
+  const jpeg = await snapshot.export({ format: "jpeg", destination: "/tmp/frame.jpg", quality: 85 });
+  await Promise.all([png.done, jpeg.done]); // terminal states, not errors
+} finally {
+  await snapshot.dispose();
+}
+```
+
 ### ExportOptions
 
 One frame as PNG, JPEG (`quality` 1–100, default 90) or BMP (24-bit), or
@@ -9015,31 +9661,121 @@ type JobState = Omit<MediaJob, "jobId">;
 
 An export, from Snapshot.export. Disposing an unfinished job cancels it.
 
+One export, from Snapshot.export. `state` is the SDK's last copy
+of the job's state: the SDK polls the player about every 350 ms until the
+job ends, and `refresh` reads it at once. `done` resolves
+once the job is terminal (`completed`, `failed` or `cancelled`) and never
+rejects for a failed export: the failure is in `outcome`. Disposing an
+unfinished job cancels it.
+
+- @capability media.read and media.control
+
 ```ts
 interface ExportJob extends Disposable {
   /** Latest state. */
   readonly state: JobState;
-  /** The state changed. */
+  /**
+   * The state changed.
+   * @capability media.read
+   * @example Log each state of an export
+   * The plugin's log records each status the job goes through (`queued`,
+   * `running`, `cancelling` after a cancel, then a terminal one). The listener runs when the SDK learns a
+   * new state from its polling.
+   * ```ts
+   * job.onChange((state) => console.log("export", state.status));
+   * ```
+   */
   onChange(listener: (state: JobState) => void): Disposable;
-  /** Resolves with the terminal state (completed, failed or cancelled). */
+  /**
+   * Resolves with the terminal state (completed, failed or cancelled).
+   * @throws disposed (rejects) The job handle was disposed while waiting.
+   */
   readonly done: Promise<JobState>;
-  /** Ask to cancel: `requested`, `tooLate` (already publishing) or `terminal` (already over). */
+  /**
+   * Ask to cancel: `requested`, `tooLate` (already publishing) or `terminal` (already over).
+   * @capability media.control
+   * @throws rejected (rejects) The player did not accept the request.
+   * @throws capability (rejects) The manifest does not declare `media.control`.
+   * @example Cancel an export the user no longer wants
+   * The running export stops, unless it is already writing its file.
+   * `cancel` resolves `requested` when the worker will stop (the job ends
+   * `cancelled`), `tooLate` when it is already publishing the file, and
+   * `terminal` when the job had already ended.
+   * ```ts
+   * const answer = await job.cancel();
+   * if (answer === "tooLate") await plugin.osd.show("Too late: the file is being written");
+   * ```
+   */
   cancel(): Promise<"requested" | "tooLate" | "terminal">;
-  /** Read the state from the player now. */
+  /**
+   * Read the state from the player now.
+   * @capability media.read
+   * @throws capability (rejects) The manifest does not declare `media.read`.
+   * @example Read a job's state now
+   * The plugin reads the newest state of an export without waiting for an
+   * event. `refresh` asks the player and resolves with the state, which
+   * `state` then holds.
+   * ```ts
+   * const state = await job.refresh();
+   * console.log(state.status);
+   * ```
+   */
   refresh(): Promise<JobState>;
 }
 ```
 
+Example: Show export progress and cancel on request
+
+The OSD shows the job's status while it runs, and a Cancel command stops
+it. `onChange` follows the state (`queued`, `running`, `cancelling`,
+then a terminal one); `cancel` asks the worker to stop. After
+`requested` the job usually ends `cancelled`, or `failed` when the
+cleanup failed.
+```ts
+job.onChange((state) => void plugin.osd.show("Export: {}", [state.status]));
+plugin.commands.add({ id: "cancel-export", title: "Cancel export", run: () => job.cancel() });
+await job.done; // completed, failed or cancelled
+```
+
 ### MediaCapture
 
 `plugin.media`: snapshots and exports. Needs `media.read` and
 `media.control` (processed snapshots also `playback.read` and
 `subtitles.read`). Exports decode offline and do not disturb playback.
 
+Exports run in the player's offline worker from a frozen
+Snapshot: a still frame or a clip, raw or with this plugin's
+effects (and the primary subtitle). Playback is not disturbed. A plugin
+holds at most 4 snapshots at a time (16 in the player); release them
+when done.
+
+- @capability media.read and media.control (processed snapshots also `playback.read` and `subtitles.read`)
+
 ```ts
 interface MediaCapture {
   /**
-   * Freeze the current source (and optionally this plugin set's effects) as an input for exports. Fails `stale` when the source changed since `ifCurrent`; `unsupported` for an external ASS track with subtitles; `noSource` when nothing is playing.
+   * Freeze the current source (and optionally this plugin set's effects) as an input for exports. Fails `stale` when the source changed since `ifCurrent`; `unsupported` for subtitles that cannot be flattened (only plain SRT text can) or a picture over the size limits; `noSource` when nothing is playing.
+   * @capability media.read and media.control
+   * @throws stale (rejects) The source changed since `ifCurrent`.
+   * @throws noSource (rejects) Nothing is playing.
+   * @throws invalid (rejects) `at` at or after the end of the source.
+   * @throws busy (rejects) This plugin holds 4 snapshots (or the player 16); release one.
+   * @throws unavailable (rejects) A processed snapshot while the picture is still being prepared.
+   * @throws unsupported (rejects) A processed snapshot the player cannot freeze: subtitles that cannot be flattened (only plain SRT text can), or a picture over the size limits.
+   * @throws capability (rejects) The manifest does not declare `media.read` and `media.control`.
+   * @example Freeze the frame at the 10-second mark
+   * The plugin freezes the frame at 0:10 of the open file, raw, to export it
+   * later. `capture` resolves with a `Snapshot` once the player has frozen
+   * that input; the snapshot stays valid when playback moves on or the file
+   * changes, until it is released.
+   * ```ts
+   * const snapshot = await plugin.media.capture({ at: 10 }); // seconds
+   * try {
+   *   // … export it …
+   * } finally {
+   *   await snapshot.dispose(); // frees one of the plugin's 4 snapshot slots
+   * }
+   * ```
    */
   capture(options?: CaptureOptions): Promise<Snapshot>;
 }
@@ -9192,25 +9928,84 @@ interface ResolvedStream {
 
 A registered resolver. Disposing it unregisters it and aborts resolutions in flight.
 
+A registered resolver, from Resolvers.add. Disposing it, its
+scope or stopping the plugin unregisters it and aborts resolutions in
+flight; the extensions or hosts are free again for other plugins.
+
+- @capability source.resolve
+
 ```ts
 interface Resolver extends Disposable {
   /**
    * Resolves when the player registered it; rejects otherwise: `conflict` when another resolver has the extension or the scheme + host (another plugin's: activation goes on; this plugin's own: activation fails), `invalid` for a malformed declaration (a player before 0.4.1 also for `extensions`).
+   * @throws conflict (rejects) Another resolver has the extension or the scheme + host, or this plugin already registered this id.
+   * @throws busy (rejects) The player already holds 16 resolvers.
+   * @throws invalid (rejects) A malformed declaration.
+   * @throws capability (rejects) The manifest does not declare `source.resolve`.
    */
   readonly ready: Promise<void>;
 }
 ```
 
+Example: Report when another plugin already handles the format
+
+The plugin tells the user when its `.ch8` resolver could not register
+because another plugin holds that extension. `ready` rejects with
+`conflict`; for another plugin's claim that does not fail activation, so
+the plugin keeps running without the resolver.
+```ts
+const resolver = plugin.resolvers.add({
+  id: "chip8",
+  extensions: ["ch8"],
+  async resolve() {
+    throw plugin.i18n.error("Not ready yet.");
+  },
+});
+// Rejects with `conflict` when the extension is taken.
+resolver.ready.catch((error: PluginError) => {
+  if (error.code === "conflict") void plugin.osd.show("Another plugin plays .ch8 files");
+});
+```
+
 ### Resolvers
 
 `plugin.resolvers`: turn web page URLs into playable streams, or local
 files into streams this plugin generates. Needs `source.resolve` (file
 resolvers also `producer.av`).
 
+A resolver turns something the player cannot play by itself into
+something it can: a web page address into stream URLs
+(WebResolverOptions), or a local file of a format the plugin
+understands into a stream the plugin generates
+(FileResolverOptions). The player asks the resolver whenever
+anyone opens a matching address or file (the Open dialog, the playlist,
+another plugin), so the plugin does not intercept opens itself.
+
+- @capability source.resolve (file resolvers also `producer.av`)
+
 ```ts
 interface Resolvers {
   /**
    * Register a resolver. When anyone opens a matching URL or file the player calls `resolve`; `signal` aborts when the open is cancelled or replaced. One scheme + host pair, and one extension, has one resolver (`conflict` otherwise). A rejected `resolve` fails the open with the error's message.
+   * @capability source.resolve
+   * @example Play a site's pages through the plugin
+   * Opening a `https://video.example.com/…` address plays the page's video.
+   * `add` returns at once and registers in the background (`ready` reports
+   * the answer); from then on the player calls `resolve` for every matching
+   * open, and the error a rejected `resolve` carries is what the user sees.
+   * ```ts
+   * plugin.resolvers.add({
+   *   id: "example",
+   *   schemes: ["https"],
+   *   hosts: ["video.example.com"], // exact host names
+   *   async resolve(url, signal) {
+   *     const response = await fetch(url, { signal });
+   *     if (!response.ok) throw new Error(`the page answered ${response.status}`);
+   *     const page = (await response.json()) as { title: string; stream: string };
+   *     return { kind: "media", originalUrl: url, title: page.title, primary: { url: page.stream } };
+   *   },
+   * });
+   * ```
    */
   add(options: ResolverOptions): Resolver;
   /**
@@ -9363,6 +10158,15 @@ interface InstallOptions {
 
 A validated package directory, from Packages.validate.
 
+A package the player has checked, from Packages.validate or
+Packages.validateArchive: its manifest, digest and the checks
+it passed. The player copies the whole package when it checks it and
+installs that copy, so later changes to the directory do not matter.
+Installing starts a PackageChange; the player keeps only the 32
+most recent candidates.
+
+- @capability plugins.manage
+
 ```ts
 interface PackageCandidate {
   /** The package directory. */
@@ -9375,11 +10179,38 @@ interface PackageCandidate {
   readonly checks: string[];
   /**
    * Install it. The same source upgrades the installed plugin (its data stays); another source fails with `conflict` unless `replace` is set; a built-in id fails with `unsupported` (built-ins update with the player). A reserved id (`vestra` or `vestra.*`, which every built-in uses) fails with `reserved` (player 0.4.1; already when validated), as only the player installs built-in plugins.
+   * @capability plugins.manage
+   * @throws conflict (rejects) The plugin is installed from another source and `replace` is not set.
+   * @throws unsupported (rejects) A built-in plugin's id.
+   * @throws reserved (rejects) A reserved id (`vestra`, `vestra.*`).
+   * @throws busy (rejects) The plugin library is being cleaned up, or the player already keeps 64 change records.
+   * @throws revisionConflict (rejects) The installed revision of this plugin changed meanwhile; call `install` again (no new validation needed).
+   * @throws stale (rejects) The candidate is older than the 32 the player keeps.
+   * @throws capability (rejects) The manifest does not declare `plugins.manage`.
+   * @example Replace a plugin installed from another source
+   * The new package replaces the installed plugin even though it came from
+   * another source. Without `replace` the player refuses with `conflict`;
+   * the same source simply upgrades and keeps the plugin's data.
+   * ```ts
+   * const change = await candidate.install({ replace: true });
+   * await change.done; // "committed" once the new plugin runs
+   * ```
    */
   install(options?: InstallOptions): Promise<PackageChange>;
 }
 ```
 
+Example: Show what a package asks for before installing it
+
+Before installing, the plugin shows the package's name and the
+capabilities it declares. The candidate's `manifest` is the manifest
+as the player read it.
+```ts
+const candidate = await plugin.packages.validate(directory);
+const { id, version, capabilities } = candidate.manifest;
+await plugin.osd.show("{} {}: {}", [id, version, capabilities.join(", ")]);
+```
+
 ### PackageChangeStatus
 
 The progress of an install or uninstall.
@@ -9393,21 +10224,71 @@ type PackageChangeStatus = "preparing" | "activating" | "restoring" | "committed
 An install or uninstall in progress. The SDK never submits a
 change twice: after a lost reply it only queries the same request.
 
+An install or uninstall the player carries out in steps (`preparing`,
+`activating`, possibly `restoring`) until a terminal status. The SDK
+asks the player for the status about every 400 ms until then; `done`
+resolves with the terminal status and does not reject for a failed
+change: `message` says why.
+
+- @capability plugins.manage
+
 ```ts
 interface PackageChange {
   /** Current status. */
   readonly status: PackageChangeStatus;
   /** Details for failures, `null` otherwise. */
   readonly message: string | null;
-  /** The status changed. */
+  /**
+   * The status changed.
+   * @capability plugins.manage
+   * @example Close a progress window when the change ends
+   * The plugin's progress window closes once the install is over, whatever
+   * the outcome. The listener receives each new status; the terminal ones
+   * are `committed`, `cancelled`, `failed`, `failedDegraded` and `tooLate`
+   * (`tooLate` only answers a `cancel` of a change that had committed, and
+   * `committed` may follow it).
+   * ```ts
+   * change.onChange((status) => {
+   *   if (["committed", "cancelled", "failed", "failedDegraded", "tooLate"].includes(status))
+   *     void progress.close();
+   * });
+   * ```
+   */
   onChange(listener: (status: PackageChangeStatus) => void): Disposable;
-  /** Resolves with the final status. */
+  /**
+   * Resolves with the final status.
+   * @throws missing (rejects) The player no longer knows the change (a `HostError` with that code); a failed change is a terminal status, not a rejection.
+   */
   readonly done: Promise<PackageChangeStatus>;
-  /** Ask to cancel (it may be `tooLate`). */
+  /**
+   * Ask to cancel (it may be `tooLate`).
+   * @capability plugins.manage
+   * @throws capability (rejects) The manifest does not declare `plugins.manage`.
+   * @example Cancel an install the user no longer wants
+   * The install stops if it has not gone too far. `cancel` asks the player;
+   * the change then ends `cancelled`. When the change had already committed
+   * the player answers `tooLate` and `done` still resolves `committed`; a
+   * change that is restoring cannot be cancelled and ends `failed` or
+   * `failedDegraded`.
+   * ```ts
+   * await change.cancel();
+   * console.log(await change.done); // "cancelled"; "committed" when it was too late
+   * ```
+   */
   cancel(): Promise<void>;
 }
 ```
 
+Example: Report each step of an install
+
+The OSD shows each step of the install and the end result. `onChange`
+runs for every new status; `done` resolves when the change is over.
+```ts
+change.onChange((status) => void plugin.osd.show("Install: {}", [status]));
+const end = await change.done;
+if (end !== "committed") await plugin.osd.show("Not installed: {}", [change.message ?? end]);
+```
+
 ### PluginInfo
 
 One plugin as the player knows it (`packages.list`).
@@ -9489,6 +10370,14 @@ interface PluginWarning {
 `plugin.packages`: the plugins the player knows. `list` and `onChange`
 need no capability; everything else needs `plugins.manage`.
 
+The plugins the player knows: installed, built-in and this run's
+development loads. Reading the list needs no capability; installing,
+enabling, reloading and uninstalling need `plugins.manage` and act on
+other plugins, never on the calling one. Built-in plugins update with
+the player and cannot be installed, disabled or uninstalled.
+
+- @capability None for `list` and `onChange`; plugins.manage for the rest.
+
 ```ts
 interface Packages {
   /**
@@ -9499,18 +10388,93 @@ interface Packages {
    * The player keeps the 32 most recent candidates of all plugins; an
    * older one's `install` fails with `stale` (validate again). Before
    * player 0.4.2 the 33rd validation of a run failed with `busy` instead.
+   * @capability plugins.manage
+   * @throws host (rejects) Not a package directory, or a manifest that breaks the rules (another `apiVersion` included); `message` says why.
+   * @throws invalid (rejects) A bad request (a path that is not a string).
+   * @throws javascript (rejects) The entry module does not parse.
+   * @throws slint (rejects) A Slint file does not compile.
+   * @throws reserved (rejects) A reserved id (`vestra`, `vestra.*`).
+   * @throws versionMismatch (rejects) The package's `minPlayerVersion` is newer than the player.
+   * @throws disabled (rejects) The calling plugin is stopping.
+   * @throws capability (rejects) The manifest does not declare `plugins.manage`.
+   * @example Check a package directory before installing it
+   * The plugin checks a folder it unpacked and installs it if the player
+   * accepts it. `validate` runs the player's checks and resolves with a
+   * candidate; a package that fails them rejects with the reason.
+   * ```ts
+   * try {
+   *   // Rejects with the reason when the package fails the checks.
+   *   const candidate = await plugin.packages.validate(directory);
+   *   await (await candidate.install()).done;
+   * } catch (error) {
+   *   await plugin.osd.show("Not a valid plugin: {}", [(error as Error).message]);
+   * }
+   * ```
    */
   validate(directory: string): Promise<PackageCandidate>;
   /**
    * Validate a `.vxp` package file (`plugins.manage`, player 0.2.0): the same checks as Packages.validate after unpacking. Check the file's sha256 yourself before calling when you know it. A reserved id fails with `reserved`, as in Packages.validate.
+   * @capability plugins.manage
+   * @throws invalid (rejects) The path does not end in `.vxp`, or the archive cannot be unpacked (over 64 MB, too many files, a damaged zip, an unsafe path).
+   * @throws host (rejects) The unpacked package or its manifest breaks the rules; `message` says why.
+   * @throws javascript (rejects) The entry module does not parse.
+   * @throws slint (rejects) A Slint file does not compile.
+   * @throws reserved (rejects) A reserved id.
+   * @throws versionMismatch (rejects) The package's `minPlayerVersion` is newer than the player.
+   * @throws disabled (rejects) The calling plugin is stopping.
+   * @throws capability (rejects) The manifest does not declare `plugins.manage`.
+   * @example Install a downloaded package file
+   * A `.vxp` the plugin downloaded is checked and installed. The player
+   * unpacks and checks it like a directory; checking the file's sha256
+   * first, when the store publishes one, is up to the plugin.
+   * ```ts
+   * const candidate = await plugin.packages.validateArchive(file); // a .vxp path
+   * const change = await candidate.install();
+   * await plugin.osd.show("Install: {}", [await change.done]);
+   * ```
    */
   validateArchive(file: string): Promise<PackageCandidate>;
-  /** Every plugin: running, installed, and this run's development loads. No capability. */
+  /**
+   * Every plugin: running, installed, and this run's development loads. No capability.
+   * @capability None.
+   * @throws Error (rejects) Only when the player cannot be asked; no capability is needed.
+   * @example Show which plugins are running
+   * The plugin lists the running plugins by name. `list` asks the player
+   * and resolves with every plugin it knows, with its state, origin and
+   * display texts in the interface language.
+   * ```ts
+   * const plugins = await plugin.packages.list();
+   * const running = plugins.filter((info) => info.state === "running");
+   * console.log(running.map((info) => info.display?.name ?? info.id));
+   * ```
+   */
   list(): Promise<PluginInfo[]>;
-  /** The new list after any start, stop, failure, install or uninstall. No capability. */
+  /**
+   * The new list after any start, stop, failure, install or uninstall. No capability.
+   * @capability None.
+   * @example Refresh a plugin list after any change
+   * A store window's list updates when a plugin starts, stops, fails, is
+   * installed or uninstalled. The listener receives the new list each time.
+   * ```ts
+   * plugin.packages.onChange((plugins) => console.log(plugins.length, "plugins"));
+   * ```
+   */
   onChange(listener: (plugins: PluginInfo[]) => void): Disposable;
   /**
-   * Stop or start a plugin (`plugins.manage`). An installed plugin stays disabled across launches; a development load only for this run. `invalid` to disable oneself, `missing` unknown. `busy` while it is being installed. `unsupported` to disable a built-in (PluginInfo.builtin): users manage third-party plugins only (players released with SDK 1.5.18 on; older ones disabled built-ins too).
+   * Stop or start a plugin (`plugins.manage`). An installed plugin stays disabled across launches; a development load only for this run. `invalid` to disable oneself, `missing` unknown. `busy` while it is being installed or reloaded. `unsupported` to disable a built-in (PluginInfo.builtin): users manage third-party plugins only (players released with SDK 1.5.18 on; older ones disabled built-ins too).
+   * @capability plugins.manage
+   * @throws invalid (rejects) Disabling the calling plugin itself.
+   * @throws missing (rejects) An unknown id.
+   * @throws busy (rejects) The plugin is being installed or reloaded.
+   * @throws unsupported (rejects) A built-in plugin.
+   * @throws capability (rejects) The manifest does not declare `plugins.manage`.
+   * @example Turn a third-party plugin off
+   * The plugin stops another plugin and keeps it disabled across launches
+   * until it is enabled again. Built-in plugins cannot be disabled
+   * (`unsupported`).
+   * ```ts
+   * await plugin.packages.setEnabled("someone.demo", false);
+   * ```
    */
   setEnabled(id: string, enabled: boolean): Promise<void>;
   /**
@@ -9528,10 +10492,38 @@ interface Packages {
    * `invalid` for oneself or a disabled plugin (enable it instead),
    * `missing` unknown, `busy` while it is being installed or reloaded.
    * @player 0.5.1; older players reject it as an unknown request (`unsupported`).
+   * @capability plugins.manage
+   * @throws invalid (rejects) The calling plugin itself, or a disabled plugin.
+   * @throws missing (rejects) An unknown id.
+   * @throws busy (rejects) The plugin is being installed or reloaded.
+   * @throws unsupported (rejects) A player before 0.5.1.
+   * @throws capability (rejects) The manifest does not declare `plugins.manage`.
+   * @example Restart a plugin that misbehaves
+   * The other plugin is stopped and started again from the same package and
+   * data. `reload` resolves once the old process is stopped and the start is
+   * scheduled; `onChange` then shows `starting` and `running` (or `failed`).
+   * ```ts
+   * await plugin.packages.reload("someone.demo");
+   * ```
    */
   reload(id: string): Promise<void>;
   /**
    * Remove an installed plugin (`plugins.manage`); `removeData` also deletes its data directory, otherwise reinstalling it from the same source reconnects to its data. Its user bindings stay (as orphans). `unsupported` for built-ins and development loads, `missing` unknown, `invalid` for oneself.
+   * @capability plugins.manage
+   * @throws unsupported (rejects) A built-in plugin or a development load.
+   * @throws missing (rejects) An unknown id.
+   * @throws invalid (rejects) The calling plugin itself.
+   * @throws busy (rejects) The plugin library is being cleaned up, or that plugin is being installed or reloaded.
+   * @throws revisionConflict (rejects) The installed revision of that plugin changed meanwhile; call `uninstall` again.
+   * @throws capability (rejects) The manifest does not declare `plugins.manage`.
+   * @example Uninstall a plugin together with its data
+   * The other plugin is removed and its data directory deleted, so a later
+   * reinstall starts fresh. Without `removeData` a reinstall from the same
+   * source finds its data again.
+   * ```ts
+   * const change = await plugin.packages.uninstall("someone.demo", { removeData: true });
+   * await change.done;
+   * ```
    */
   uninstall(id: string, options?: {
     removeData?: boolean;
@@ -9606,9 +10598,31 @@ interface BindingInfo extends BindingRef {
 `plugin.bindings`: list and override every command's bindings, including
 the player's. Needs `bindings.manage`.
 
+The player's binding table: every command's default keys (from
+CommandOptions.bindings, the player's own as `host/<action>`)
+and the user's overrides on top, saved across launches. A key-settings
+plugin lists the table, writes overrides and resets them; the player
+applies the change at once to every running plugin.
+
+- @capability bindings.manage
+
 ```ts
 interface Bindings {
-  /** Every declared command, and overrides whose command is gone. */
+  /**
+   * Every declared command, and overrides whose command is gone.
+   * @capability bindings.manage
+   * @throws capability (rejects) The manifest does not declare `bindings.manage`.
+   * @example Find the commands that use a key
+   * A key-settings window shows which commands Ctrl+K is bound to now. `list`
+   * resolves with every declared command and its current bindings (the
+   * defaults with the user's overrides applied) and with the overrides
+   * whose command is not running (`orphans`).
+   * ```ts
+   * const { commands } = await plugin.bindings.list();
+   * const users = commands.filter((command) => command.current.includes("Ctrl+K"));
+   * console.log(users.map((command) => `${command.plugin}/${command.command}`)); // "host" for the player
+   * ```
+   */
   list(): Promise<{
     /** Every declared command (running plugins and the player). */
     commands: BindingInfo[];
@@ -9622,11 +10636,47 @@ interface Bindings {
   }>;
   /**
    * Override a command's bindings (`[]` unbinds it); saved across launches. `invalid` for a bad binding, `missing` for an unknown command that has no override either. At most 16 inputs, syntax as CommandOptions.bindings.
+   * @capability bindings.manage
+   * @throws invalid (rejects) A malformed binding, or more than 16.
+   * @throws missing (rejects) An unknown command that has no override either.
+   * @throws capability (rejects) The manifest does not declare `bindings.manage`.
+   * @example Give the player's Mute command a second key
+   * Mute now answers to M and to Ctrl+M. `set` replaces the command's
+   * bindings with the list given (an override saved across launches), so it
+   * repeats the default it keeps; `[]` would unbind it.
+   * ```ts
+   * await plugin.bindings.set({ plugin: "host", command: "mute" }, ["M", "Ctrl+M"]);
+   * ```
    */
   set(ref: BindingRef, inputs: string[]): Promise<void>;
-  /** Back to the defaults: one command, or every override when omitted. */
+  /**
+   * Back to the defaults: one command, or every override when omitted.
+   * @capability bindings.manage
+   * @throws missing (rejects) A command that has no override and is not declared.
+   * @throws capability (rejects) The manifest does not declare `bindings.manage`.
+   * @example Restore every default key
+   * A "Restore defaults" button removes all of the user's overrides, so
+   * every command has its declared keys again. Without an argument `reset`
+   * clears every override; with a reference only that command's.
+   * ```ts
+   * await plugin.bindings.reset(); // every override
+   * ```
+   */
   reset(ref?: BindingRef): Promise<void>;
-  /** Declarations or overrides changed (read `list()` again). At most every 200 ms. */
+  /**
+   * Declarations or overrides changed (read `list()` again). At most every 200 ms.
+   * @capability bindings.manage
+   * @example Refresh a key list when bindings change
+   * The plugin's key list stays current when the user changes a key in the
+   * player or another plugin starts. The listener carries no data and runs
+   * at most every 200 ms; the plugin reads the table again with `list`.
+   * ```ts
+   * plugin.bindings.onChange(async () => {
+   *   const { commands } = await plugin.bindings.list(); // read the new table
+   *   render(commands);
+   * });
+   * ```
+   */
   onChange(listener: () => void): Disposable;
 }
 ```
@@ -10717,6 +11767,13 @@ A tool window as the test host keeps it: the record of a
 `plugin.windows.create(...)` window after its first `show()`. Get one with
 TestHost.window.
 
+A record, not a window: no Slint file is compiled and nothing is drawn.
+`props` holds what the plugin wrote, by Slint name; `emit` fires a
+callback the way the user's input would; `userClose` closes it the way
+the title-bar button would.
+
+- @capability None.
+
 ```ts
 interface FakeWindow {
   /** The `.slint` file the window was created from (package-relative). */
@@ -10731,10 +11788,32 @@ interface FakeWindow {
   callbacks: string[];
   /**
    * Fire a Slint callback as if the user triggered it in the window. The name may be kebab-case or camelCase; `args` are the callback arguments. Follow it with `await host.settle()` before asserting.
+   * @capability None.
+   * @example Type into a window's search field
+   * The test types "cat" into the window's search box and checks the
+   * plugin's results. `emit` delivers the Slint callback `search-changed`
+   * with its argument to the plugin's `on` handler; `settle()` waits for the
+   * properties the handler wrote.
+   * ```ts
+   * const search = host.window("search");
+   * search.emit("searchChanged", "cat"); // camelCase or kebab-case
+   * await host.settle();
+   * assert.ok((search.props["results"] as unknown[]).length > 0);
+   * ```
    */
   emit(callback: string, ...args: Json[]): void;
   /**
    * The user closes the window with its title-bar button: the window closes and the plugin's `window.onClose` listeners run (unlike the plugin's own `close()`).
+   * @capability None.
+   * @example Close a window the way the user does
+   * The test closes the plugin's window with its title-bar button and checks
+   * that the plugin stopped its timer. Unlike the plugin's own `close()`,
+   * `userClose` runs the plugin's `onClose` listeners.
+   * ```ts
+   * host.window("clock").userClose();
+   * await host.settle();
+   * assert.equal(host.window("clock").visible, false);
+   * ```
    */
   userClose(): void;
 }
@@ -10777,6 +11856,13 @@ A command the plugin registered with `plugin.commands.add`, as the test
 host keeps it. Get one with TestHost.command (the plugin's own) or
 TestHost.coreAction (the player's core actions).
 
+The host's record of one command: what the plugin declared, the state
+it last sent, and how the menu shows it in TestHost.locale.
+Read it again after `settle()` to see changes; `run` executes it as the
+menu would.
+
+- @capability None.
+
 ```ts
 interface FakeCommand {
   /** What the plugin declared: id, menu path, title, order, group, default bindings, focus and repeat. Wire-level shape; it may gain fields in minor versions. */
@@ -10809,6 +11895,15 @@ interface FakeCommand {
   revision: number;
   /**
    * Execute the command the way the menu would, then wait until the host is idle. Rejects (with a HostError) when the command is disabled or busy, like the player, which does not call `run` then.
+   * @capability None.
+   * @throws command (rejects) A `HostError`: the command is disabled or busy (the message says which).
+   * @example Check that a disabled item refuses to run
+   * The test checks that Export cannot run while nothing is open. Like the
+   * player, the host does not call `run` for a disabled or busy command;
+   * the promise rejects with a `HostError`.
+   * ```ts
+   * await assert.rejects(host.command("export").run());
+   * ```
    */
   run(): Promise<void>;
 }
@@ -10834,6 +11929,13 @@ assert.equal(host.command("toggle-loop").state.checked, true);
 A command's bottom-bar button (`CommandOptions.button`) as the player shows
 it: an entry of TestHost.barButtons.
 
+A bottom-bar button as the player would show it, derived from the
+command's declaration and state each time it is read: clickable while
+the command is enabled and not busy, accent-coloured while checked, with
+the command's title (and reason) as the tooltip.
+
+- @capability None.
+
 ```ts
 interface FakeBarButton {
   /** The command's local id. */
@@ -10852,17 +11954,45 @@ interface FakeBarButton {
   readonly tooltip: string;
   /**
    * Click the button, then wait until the host is idle: runs the command as its menu item would. Rejects (with a HostError) while the button is disabled, and once the command is gone.
+   * @capability None.
+   * @throws command (rejects) A `HostError`: the command is disabled or busy.
+   * @throws missing (rejects) A `HostError`: the command is gone.
+   * @example Click the button and wait for its effect
+   * The test clicks the plugin's button and checks the OSD. `click` runs the
+   * command like its menu item and resolves once the host is idle.
+   * ```ts
+   * await host.barButtons[0]?.click();
+   * assert.ok(host.osd.length > 0);
+   * ```
    */
   click(): Promise<void>;
 }
 ```
 
+Example: Check a bar button's tooltip while it is disabled
+
+The test checks that the Export button shows why it cannot be clicked.
+The tooltip is the command's title; while the command is disabled or
+busy and has a non-empty `reason`, the reason follows on a second line.
+```ts
+const [button] = host.barButtons;
+assert.equal(button?.enabled, false);
+assert.match(button?.tooltip ?? "", /\n/); // the command declares a reason
+```
+
 ### FakeProducer
 
 A generated stream (`plugin.player.openStream`) as the test host sees it:
 the fake player end of the frame connection. Assertion surface; see
 TestHost.producers.
 
+The player's end of a generated stream's frame connection
+(TestHost.producers): how many frames arrived and whether the
+plugin released it or the player retired it. Tests assert on it; nothing
+is played.
+
+- @capability None.
+
 ```ts
 interface FakeProducer {
   /** The producer id the host assigned (`1`, `2`, … per host). */
@@ -10884,6 +12014,18 @@ interface FakeProducer {
 }
 ```
 
+Example: Check that the stream delivers frames
+
+The test starts the plugin's generator and checks that video and audio
+arrive. The counters grow as the SDK pulls frames and sends them over
+the fake connection.
+```ts
+await host.command("start-generator").run();
+await host.settle(200); // let a few frames through
+const [producer] = host.producers.values();
+assert.ok((producer?.videoFrames ?? 0) > 0 && (producer?.receivedFrames ?? 0) > 0);
+```
+
 ### MarkdownWire
 
 A Markdown document as TestHost.markdown reads it back.
@@ -10938,6 +12080,15 @@ Fields that mirror player state at the wire level (`source`, `subtitles`,
 `calls`) use the protocol's shapes. They are fine for assertions but are
 not part of the plugin API: their shape may change in minor versions.
 
+An in-memory player that speaks the real wire protocol, so the SDK's own
+logic runs as it does in the player; only the player side is simulated
+(no decoding, no Slint, no windows). Make one per test, preset it if the
+plugin reads something during activation, start the plugin with
+startPlugin, drive it, `settle()`, and assert on what it
+recorded.
+
+- @capability None.
+
 ```ts
 class TestHost implements Transport {
   /** Every request the plugin sent, in order: `{ method, params }`. Wire-level; prefer TestHost.sent for one method. */
@@ -11020,6 +12171,15 @@ class TestHost implements Transport {
   /**
    * Read the plugin's translations for TestHost.locale from a package directory, as the player would (`locales/<locale>.json` of a built package, else the source `locales/<locale>.po`); `startPlugin` does this. None for English; a missing file means none; a broken `.po` throws.
    * @param directory - The package directory (holding `locales/`).
+   * @capability None.
+   * @example Load the translations after changing the language
+   * The test switches the host to German before starting the plugin and
+   * loads that catalog itself (`startPlugin` does the same). Texts are then
+   * shown in German.
+   * ```ts
+   * host.locale = "de";
+   * host.loadCatalog(directory); // locales/de.po (or de.json)
+   * ```
    */
   loadCatalog(directory: string): void;
   /**
@@ -11027,6 +12187,7 @@ class TestHost implements Transport {
    * @param text - English source text or template.
    * @param args - Values for its placeholders.
    * @returns The shown text.
+   * @capability None.
    * @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
@@ -11041,6 +12202,19 @@ class TestHost implements Transport {
   /**
    * Simulate another plugin (or the user) saving the interface language: pushes `appearance.changed`.
    * @param language - `"system"` or a locale.
+   * @capability None.
+   * @example Simulate the user choosing French for the next start
+   * The plugin hears that the saved interface language changed. The host
+   * pushes `appearance.changed`, which a plugin with `events` sees in
+   * `appearance.language` once it has read it and subscribed; this run's
+   * language does not change.
+   * ```ts
+   * void plugin.appearance.language; // read once: the SDK then follows it
+   * plugin.appearance.onChange(() => {}); // subscribes to appearance events
+   * host.setLanguage("fr");
+   * await host.settle();
+   * assert.equal(plugin.appearance.language, "fr");
+   * ```
    */
   setLanguage(language: LanguagePreference): void;
   /**
@@ -11197,6 +12371,7 @@ 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.
+   * @capability None.
    * @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
@@ -11230,6 +12405,7 @@ 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.
+   * @capability None.
    * @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
@@ -11255,6 +12431,8 @@ class TestHost implements Transport {
    * 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`).
+   * @capability None.
+   * @throws Never: files nobody takes are ignored, as in the player.
    * @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
@@ -11285,7 +12463,20 @@ class TestHost implements Transport {
   }): Promise<void>;
   /** The palette (`plugin.appearance.theme`); `setAppearance` changes it elsewhere. */
   appearance: ThemeId;
-  /** Simulate another plugin switching the palette: updates TestHost.appearance and pushes `appearance.changed`. */
+  /**
+   * Simulate another plugin switching the palette: updates TestHost.appearance and pushes `appearance.changed`.
+   * @capability None.
+   * @example Simulate another plugin switching to the light palette
+   * The plugin hears the palette change. The host updates `appearance` and
+   * pushes `appearance.changed` to a plugin that listens with `events`.
+   * ```ts
+   * const themes: ThemeId[] = [];
+   * plugin.appearance.onChange((theme) => themes.push(theme)); // subscribes (`events`)
+   * host.setAppearance("vestra-light");
+   * await host.settle();
+   * assert.deepEqual(themes, ["vestra-light"]);
+   * ```
+   */
   setAppearance(theme: ThemeId): void;
   /** Settings pages by id (`plugin.settings.page`), every `show` (page id or null), and the page the options window shows. */
   readonly settings: {
@@ -11317,6 +12508,7 @@ class TestHost implements Transport {
   };
   /**
    * One settings page by id. Throws when it was never registered.
+   * @capability None.
    * @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
@@ -11354,13 +12546,26 @@ class TestHost implements Transport {
     /** Whether it shows now (no video frame). `true` when mounted. */
     effective: boolean;
   } | null;
-  /** Simulate the backdrop's `effective` changing (`false`: a video frame appeared; `true`: there is none again); pushed to the plugin. */
+  /**
+   * Simulate the backdrop's `effective` changing (`false`: a video frame appeared; `true`: there is none again); pushed to the plugin.
+   * @capability None.
+   * @example Make a video picture replace the backdrop
+   * The plugin's backdrop hears that a video frame now covers it. `false`
+   * means a picture appeared; the change is pushed like the player's
+   * `window.state`.
+   * ```ts
+   * host.setBackdropEffective(false);
+   * await host.settle();
+   * assert.equal(plugin.panels.backdrop.state?.effective, false);
+   * ```
+   */
   setBackdropEffective(effective: boolean): void;
   /**
    * Simulate another plugin mounting a panel, before or after the plugin under test, as the player handles it: in the sidebar it is another tab (after the existing ones; the first panel's tab is current); the bottom bar and the backdrop take one panel, so the plugin's own mount there then rejects with `conflict` (not an activation failure, as in the player). Pushed as a `window.state` change.
    * @param slot - The position.
    * @param plugin - The other plugin's manifest id.
    * @param options - `title`: its tab label (default: `plugin`).
+   * @capability None.
    * @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
@@ -11377,10 +12582,31 @@ class TestHost implements Transport {
   mountOther(slot: "bottom" | "sidebar" | "backdrop", plugin: string, options?: {
     title?: string;
   }): void;
-  /** Simulate another plugin's panel going away (TestHost.mountOther): when its tab was current, the next tab (else the previous one) is. */
+  /**
+   * Simulate another plugin's panel going away (TestHost.mountOther): when its tab was current, the next tab (else the previous one) is.
+   * @capability None.
+   * @example Let the playlist's tab go away
+   * The other plugin's sidebar tab disappears and the plugin's own tab
+   * becomes current. When the removed tab was current, the next tab (else
+   * the previous one) becomes current, as in the player.
+   * ```ts
+   * host.unmountOther("vestra.playlist");
+   * await host.settle();
+   * assert.equal(host.layout.sidebar?.panels?.length, 1);
+   * ```
+   */
   unmountOther(plugin: string): void;
   /**
    * Simulate the user clicking a sidebar tab: `plugin`'s panel (the plugin under test's `manifestId`, or one of TestHost.mountOther) becomes the current tab. Pushed as a `window.state` change.
+   * @capability None.
+   * @example Click another plugin's sidebar tab
+   * The user switches the sidebar to the playlist; the plugin's panel is in
+   * a background tab now. The change is pushed as `window.state`.
+   * ```ts
+   * host.selectTab("vestra.playlist");
+   * await host.settle();
+   * assert.notEqual(host.layout.sidebar?.owner, 1); // the plugin under test is owner 1
+   * ```
    */
   selectTab(plugin: string): void;
   /** The display layer (`plugin.video.view()`): who owns it (this plugin is `manifestId`) and the values the player holds. */
@@ -11392,6 +12618,17 @@ class TestHost implements Transport {
   };
   /**
    * Simulate another plugin taking the display layer first (the plugin's `video.view()` then fails with `conflict`), or, with `null`, releasing it (values reset to the defaults).
+   * @capability None.
+   * @example Let another plugin own the display layer
+   * The plugin's `video.view()` fails with `conflict` because another plugin
+   * took the display layer first. `null` releases it again.
+   * ```ts
+   * host.setVideoViewOwner("someone.zoom");
+   * const view = plugin.video.view();
+   * view.set({ zoom: 2 });
+   * await host.settle();
+   * assert.equal(view.status.state, "failed");
+   * ```
    */
   setVideoViewOwner(pluginId: string | null): void;
   /**
@@ -11402,15 +12639,27 @@ class TestHost implements Transport {
     owner: string | null;
     /** The values the player holds. */
     values: RenderSettings;
-    /** `true`: GPU rendering; `false`: software rendering (`unsupported`). */
+    /** `true`: GPU rendering; `false`: software rendering (`unsupported`). `plugin.app.system()` reports it as `rendering`. */
     gpu: boolean;
   };
   /**
    * Simulate another plugin owning the render options (the plugin's `video.render()` then fails with `conflict`), or, with `null`, releasing them (values reset to the defaults).
+   * @capability None.
+   * @example Let another plugin own the render options
+   * The plugin's render options report `conflict` while another plugin owns
+   * them; `null` releases them and resets the values to the defaults.
+   * ```ts
+   * host.setVideoRenderOwner("someone.hdr");
+   * const render = plugin.video.render();
+   * render.set({ toneMapping: "bt.2390" });
+   * await host.settle();
+   * assert.equal(render.status.state, "failed");
+   * ```
    */
   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.
+   * @capability None.
    * @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
@@ -11479,6 +12728,8 @@ class TestHost implements Transport {
     bytes: Buffer[];
     /** The announced total size in bytes. */
     expected: number;
+    /** The source generation it was begun for; like the player, a new source drops the uploads of the old one. */
+    generation?: number;
   }>;
   /** Snapshots taken with `media.capture`, by snapshot id. Wire-level. */
   readonly snapshots: Map<number, Json>;
@@ -11531,10 +12782,21 @@ class TestHost implements Transport {
     /** Exact host names it resolves (a web resolver), with `schemes`. */
     hosts?: string[];
   }[];
-  /** What `plugin.resolvers.fileTypes` reports: the extensions of this plugin's file resolvers and of TestHost.otherResolvers, sorted, each once. */
+  /**
+   * What `plugin.resolvers.fileTypes` reports: the extensions of this plugin's file resolvers and of TestHost.otherResolvers, sorted, each once.
+   * @capability None.
+   * @example Check the file types a resolver adds
+   * The test checks the list the plugin will read as
+   * `resolvers.fileTypes`: the extensions of its own file resolvers and of
+   * `otherResolvers`, sorted, each once.
+   * ```ts
+   * assert.deepEqual(host.fileTypes(), ["ch8"]);
+   * ```
+   */
   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).
+   * @capability None.
    * @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
@@ -11621,8 +12883,10 @@ class TestHost implements Transport {
    * `plugin.storage.session`: key → value, as the player keeps them. Preset entries to simulate values an earlier run of the plugin stored in the same player session, or pass `startPlugin(..., { sessionStorage })`. Like the player, a key is 1–1024 bytes, a `set` that would make the entries larger than 1 MiB (keys, values as compact JSON and `SESSION_STORAGE_LIMITS.entryBytes` per key) fails `limit`, and an object's properties are stored sorted, as the player hands them back.
    */
   readonly sessionStorage: Map<string, Json>;
-  /** What `plugin.app.system()` reports. */
-  systemInfo: WireSystemInfo;
+  /**
+   * What `plugin.app.system()` reports. Its `rendering` follows videoRender.gpu (`"gpu"` or `"software"`), so one switch covers the render options and the fact.
+   */
+  systemInfo: Omit<WireSystemInfo, "rendering">;
   /** What `plugin.app` reports. Set it before startPlugin: the plugin receives it once at start-up. */
   app: {
     /** The player version. */
@@ -11652,6 +12916,9 @@ class TestHost implements Transport {
   readonly dataDirectory: string;
   /** The manifest id of the plugin under test (set by startPlugin; `"test.plugin"` by default). */
   manifestId: string;
+  /**
+   * A fresh in-memory player: nothing open, no plugin, the player's core actions registered. Preset what the plugin reads during activation, then pass it to startPlugin as `host`.
+   */
   constructor();
   /** The `player.setStepSeek` value in effect (default 5). */
   stepSeek: number;
@@ -11707,7 +12974,8 @@ class TestHost implements Transport {
   /** Every core action run (`host.run`, a core command, a pressed core binding), newest last. */
   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.
+   * 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 like its menu item: a disabled action rejects with `command`, as in the player (`plugin.host.run` rejects with `unavailable` instead); otherwise it runs with the player's checks and writes its on-screen text to TestHost.osd.
+   * @capability None.
    * @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>`);
@@ -11734,6 +13002,7 @@ 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.
+   * @capability None.
    * @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
@@ -11750,17 +13019,43 @@ class TestHost implements Transport {
    * ```
    */
   handle(method: string, handler: Handler): void;
-  /** Restore the default behaviour of a method replaced with TestHost.handle. */
+  /**
+   * Restore the default behaviour of a method replaced with TestHost.handle.
+   * @capability None.
+   * @example Restore the default answer after a simulated failure
+   * The first write fails, the second succeeds. `reset` removes the handler
+   * that `handle` installed, so the method is answered by the test host
+   * again.
+   * ```ts
+   * host.handle("clipboard.writeText", () => {
+   *   throw new HostError("failed", "denied");
+   * });
+   * await assert.rejects(plugin.clipboard.writeText("x"));
+   * host.reset("clipboard.writeText");
+   * await plugin.clipboard.writeText("x"); // the default handler again
+   * ```
+   */
   reset(method: string): void;
   /**
    * Deliver a host event to the plugin. Like the player, subscription-based events (`source.state`, `playback.backend`, `window.state`, `timeline.changed`, `appearance.changed`) are delivered only when the plugin subscribed (it declared `events` and listens). Most tests use the higher-level helpers (`setSource`, `setMainWindow`, ...) instead.
    * @param event - The wire event name.
    * @param data - The event payload (wire-level shape).
+   * @capability None.
+   * @example Deliver a raw event the helpers do not cover
+   * The test pushes a `window.state` event after changing `layout` by hand.
+   * Like the player, the host delivers it only when the plugin subscribed;
+   * most tests use `setSource`, `setMainWindow` and the other helpers
+   * instead.
+   * ```ts
+   * host.emit("window.state", {}); // no facts: the SDK reads window.state again
+   * await host.settle();
+   * ```
    */
   emit(event: string, data: unknown): void;
   /**
    * 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`.
+   * @capability None.
    * @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
@@ -11777,6 +13072,7 @@ class TestHost implements Transport {
   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.
+   * @capability None.
    * @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
@@ -11803,12 +13099,23 @@ class TestHost implements Transport {
   }>): void;
   /**
    * The pointer reached the right edge in fullscreen (`true`) or left the popped-out sidebar (`false`): the attached sidebar pops out or collapses (reference §6.3). No effect outside fullscreen, when hidden or floating.
+   * @capability None.
+   * @example Pop the sidebar out in fullscreen
+   * The pointer reaches the right edge in fullscreen and the attached
+   * sidebar pops out over the video. Outside fullscreen, or with the
+   * sidebar hidden or floating, nothing happens.
+   * ```ts
+   * host.setMainWindow({ fullscreen: true });
+   * host.popSidebar(true);
+   * await host.settle();
+   * ```
    */
   popSidebar(popped: boolean): void;
   /**
    * 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"`).
+   * @capability None.
    * @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
@@ -11827,6 +13134,7 @@ class TestHost implements Transport {
    * 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.
+   * @capability None.
    * @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
@@ -11839,8 +13147,11 @@ class TestHost implements Transport {
    */
   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.
+   * 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"`). When only disabled commands hold the key, the first of them decides, as in the player: with a `reason` it shows the reason on the OSD and eats the key (`"reason"`, see `host.osd`); without one the key goes on to the focused control (`"passed"`, nothing runs). Unlike the player, which only logs a key that reaches a busy command, `press` then rejects, so a test notices. 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"`.
+   * @capability None.
+   * @throws command (rejects) A `HostError`: the command that would run is busy (the player only logs this).
+   * @throws Error (rejects) Nothing is bound to the key.
    * @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`
@@ -11931,6 +13242,7 @@ 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.
+   * @capability None.
    * @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
@@ -11948,13 +13260,47 @@ class TestHost implements Transport {
     /** The system's name for it. */
     name: string;
   }[];
-  /** Replace the plugin list and push `packages.changed` (another plugin started, stopped, was installed or removed). */
+  /**
+   * Replace the plugin list and push `packages.changed` (another plugin started, stopped, was installed or removed).
+   * @capability None.
+   * @example Simulate another plugin starting
+   * The plugin's store window hears that a plugin is running now. The list
+   * replaces `packages` and is pushed as `packages.changed`, which the
+   * plugin's `packages.onChange` listeners receive.
+   * ```ts
+   * host.setPackages([...host.packages]); // edit a copy, then push it
+   * await host.settle();
+   * ```
+   */
   setPackages(list: TestHost["packages"]): void;
   /**
    * Simulate another plugin calling `player.next()` / `previous()`: the host asks this plugin's sequence provider. Rejects with `unavailable` when there is no provider or its flag is false.
+   * @capability None.
+   * @throws unavailable (rejects) A `HostError`: there is no sequence provider, or its flag is false.
+   * @example Ask the plugin's provider for the next item
+   * Another plugin calls `player.next()`; the host asks the plugin under
+   * test, which is the sequence provider, and the test checks what it
+   * opened.
+   * ```ts
+   * await host.step("next");
+   * await host.settle();
+   * assert.equal(host.source.source, "/media/b.mp4");
+   * ```
    */
   step(direction: "next" | "previous"): Promise<unknown>;
-  /** The plugin's command with this local id. Throws when it is not registered (never added, or disposed). */
+  /**
+   * The plugin's command with this local id. Throws when it is not registered (never added, or disposed).
+   * @capability None.
+   * @example Read a command's state after a change
+   * The test checks that Export becomes enabled once a file is ready. The
+   * record is updated as the plugin sends new state; read it after
+   * `settle()`.
+   * ```ts
+   * host.setSource({ phase: "ready", duration: 60 });
+   * await host.settle();
+   * assert.equal(host.command("export").state.enabled, true); // throws if not registered
+   * ```
+   */
   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`.
@@ -11974,6 +13320,7 @@ class TestHost implements Transport {
   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()`.
+   * @capability None.
    * @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);
@@ -11988,6 +13335,7 @@ class TestHost implements Transport {
   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.
+   * @capability None.
    * @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;
@@ -12009,6 +13357,7 @@ class TestHost implements Transport {
   };
   /**
    * The parameters of every request of one wire method, oldest first.
+   * @capability None.
    * @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
@@ -12029,6 +13378,8 @@ 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).
+   * @capability None.
+   * @throws Never.
    * @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.
@@ -12054,7 +13405,22 @@ class TestHost implements Transport {
    * ```
    */
   settle(ms?: number): Promise<void>;
-  /** Close the fake stream servers and delete the host's temporary directories. `stop()` from startPlugin calls it. */
+  /**
+   * Close the fake stream servers and delete the host's temporary directories. `stop()` from startPlugin calls it.
+   * @capability None.
+   * @example Clean up a host that was never started
+   * A test that made a host but failed before `startPlugin` removes the
+   * host's temporary directories itself. `stop()` from `startPlugin` calls
+   * `close` for you otherwise.
+   * ```ts
+   * const host = new TestHost();
+   * try {
+   *   // … preset the host; the test fails here …
+   * } finally {
+   *   host.close(); // deletes the host's temporary data
+   * }
+   * ```
+   */
   close(): void;
 }
 ```
@@ -12104,9 +13470,14 @@ throws, or when a registration made during activation fails (for example
 `limit`, `conflict`, `invalid`), which is when the player would fail the
 activation.
 
+The way into a plugin's tests: one call starts the plugin the way the
+player's runner does and returns the host to drive, the `plugin` object
+to call directly, and `stop` to end it like the player.
+
 - @param activate - The plugin's default-exported `activate` function.
 - @param options - Where the plugin lives and how to start it.
 - @returns `host`: the TestHost; `plugin`: the object passed to `activate` (call the plugin API on it directly); `stop()`: dispose the plugin like the player stopping it (scopes released, stores flushed), wait until the host is idle and remove the host's temporary files.
+- @capability None.
 
 ```ts
 function startPlugin(activate: (plugin: Plugin) => unknown, options?: {
@@ -12751,6 +14122,61 @@ if (!token || Buffer.byteLength(token) > SECRET_LIMITS.valueBytes) {
 }
 ```
 
+### SUBTITLE_LIMITS
+
+The player's limits on subtitle files a plugin loads with
+Subtitles.load, which `TestHost` enforces with the player's codes.
+The track counts are per source: opening another file starts from zero.
+A file over `fileBytes` fails with `invalid`; every other limit fails with
+`busy`, and nothing is loaded.
+
+Each `load` uses a new resource on the source, and removing the track
+frees its place among the live tracks (`tracksPerPlugin`, `tracks`,
+`totalBytes`) but not among the loads (`loadsPerPlugin`, `loads`). So one
+plugin loads at most 16 files into one source, with at most 4 of them
+present at once.
+
+```ts
+const SUBTITLE_LIMITS: Readonly<{
+  /** UTF-8 bytes of one file; a larger one fails with `invalid` (2 MiB). */
+  readonly fileBytes: number;
+  /** Tracks one plugin has loaded into the current source at the same time (4). */
+  readonly tracksPerPlugin: 4;
+  /** Loaded tracks of every plugin in the current source at the same time (16). */
+  readonly tracks: 16;
+  /** Bytes of the loaded tracks of every plugin in the current source together (16 MiB). */
+  readonly totalBytes: number;
+  /** Loads by one plugin into the current source, removed tracks included (16). */
+  readonly loadsPerPlugin: 16;
+  /** Loads by every plugin into the current source, removed tracks included (128). */
+  readonly loads: 128;
+  /** Loads of one plugin in progress at the same time (2). */
+  readonly uploadsPerPlugin: 2;
+  /** Loads of every plugin in progress at the same time (8). */
+  readonly uploads: 8;
+}>;
+```
+
+Example: Replace the plugin's oldest subtitle when it has four
+
+The plugin keeps the files it loaded, newest last, and removes the oldest
+before a fifth would be refused with `busy`. A load the player still
+refuses (the source holds 16 tracks of every plugin, or this plugin
+already loaded 16 files into it) is reported on the OSD.
+```ts
+import { SUBTITLE_LIMITS } from "@vestra-player/sdk/testing";
+
+const loaded: SubtitleTrack[] = []; // this source's, newest last
+if (loaded.length >= SUBTITLE_LIMITS.tracksPerPlugin)
+  await plugin.subtitles.remove(loaded.shift()!);
+try {
+  loaded.push(await plugin.subtitles.load(bytes));
+} catch (error) {
+  if ((error as PluginError).code !== "busy") throw error;
+  await plugin.osd.show("No room for another subtitle on this file.");
+}
+```
+
 ### UI_VALUE_LIMITS
 
 The player's limits on one property value (a `PropValue` as written
@@ -12851,11 +14277,17 @@ Common codes: `stale` (the condition no longer holds; nothing was done),
 `timeout`, `aborted`, `limit` (a player limit such as the command count),
 `disabled` (the plugin is stopping).
 
+A definite refusal, as opposed to a lost reply: the SDK does not retry
+it, and the plugin sees an `Error` with `code`.
+
+- @capability None.
+
 ```ts
 class HostError extends Error {
   /** The stable error code, e.g. `"invalid"`, `"stale"`, `"unavailable"`. */
   code: string;
   /**
+   * A refusal with this code, as the player would send it.
    * @param code - The stable error code the caller will see as `error.code`.
    * @param message - Human-readable detail (not for branching on).
    */
@@ -13233,7 +14665,7 @@ interface SubtitleState {
 
 ### WireSystemInfo
 
-`app.system`: the operating system and the displays.
+`app.system`: the operating system, the displays and the renderer.
 
 ```ts
 interface WireSystemInfo {
@@ -13251,6 +14683,8 @@ interface WireSystemInfo {
     refreshRate: number | null;
     primary: boolean;
   }[];
+  /** Player 0.5.12; older players leave it out. */
+  rendering?: "gpu" | "software";
 }
 ```