@vestra-player/sdk 1.5.30 → 1.5.33

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.30: full reference
+# @vestra-player/sdk 1.5.33: 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.
 
@@ -1032,6 +1032,282 @@ The API is the same on macOS and Windows; what differs is the system's own part:
 
 `TestHost` from `@vestra-player/sdk/testing` runs a plugin without the player and records its interface: windows with their properties and callbacks, the mounted panel, settings pages, the OSD and dialogs. It does not compile Slint files; check them by running the plugin in the player. How to write such tests is in Test a plugin.
 
+## How-to: Control playback
+
+**Goal:** your plugin opens files and controls playback (pause, seek, speed, next and previous), shows what is playing, and never acts on a file the user has already left.
+
+The player has one source. The user, other plugins and yours all change it, so every control in `plugin.player` is **conditional**: it acts on the state your plugin last saw and fails with `stale` (doing nothing) when someone else changed the source in between. Most of this guide is about using that well.
+
+#### Capabilities
+
+```json
+{
+  "capabilities": ["commands", "playback.read", "playback.control", "events"]
+}
+```
+
+`playback.read` reads the state, `playback.control` changes it, `events` keeps `player.state` current when the change comes from elsewhere (without it, the state only moves after your own calls and `refresh()`), and `commands` gives your actions menu items and keys.
+
+#### Read the state
+
+`plugin.player.state` is a snapshot the SDK keeps current from the player's events. `onChange` runs after it changed; read the new snapshot there instead of asking the player.
+
+```ts
+const info = plugin.osd.panel();
+plugin.player.onChange((state) => {
+  // `position` and `duration` are seconds, null while unknown.
+  if (state.phase !== "ready") return info.set(null);
+  info.set("{} / {} s", [state.position?.toFixed(0) ?? "–", state.duration?.toFixed(0) ?? "–"]);
+});
+```
+
+`state.can` says which controls the current source allows (`pause`, `seek`, `rate`, `restart`, `close`, `next`, `previous`). Bind menu items to it so they grey out by themselves:
+
+```ts
+plugin.commands.add({
+  id: "pause",
+  path: ["@playback", "Pause"],
+  enabled: () => plugin.player.state.can.pause, // re-evaluated after every change
+  checked: () => plugin.player.state.paused,
+  run: () => plugin.player.setPaused(!plugin.player.state.paused),
+});
+```
+
+#### Control it, and handle `stale`
+
+A control without options is conditional on `player.state` as it is when you call. `stale` means the source changed after that: another file, a close, or any pause, seek or speed change by the user or another plugin. Nothing happened, and usually that is the right outcome:
+
+```ts
+try {
+  await plugin.player.seek(30);
+} catch (error) {
+  if ((error as PluginError).code !== "stale") throw error; // another file now
+}
+```
+
+For work that takes time (a timer, a dialog, a network request), keep the snapshot from when it started and pass it as `ifCurrent`, so the call applies only to that source:
+
+```ts
+const seen = plugin.player.state;
+const answer = await plugin.dialogs.confirm({ message: "Close this file?", confirm: "Close" }); // ui.dialog
+if (answer.confirmed)
+  await plugin.player.close({ ifCurrent: seen }).catch((error: PluginError) => {
+    if (error.code !== "stale") throw error; // the user opened something else meanwhile
+  });
+```
+
+`player.isCurrent(seen)` answers the same question without a call. Your own consecutive calls do not make each other stale: the SDK refreshes the state after each one.
+
+Other codes: `invalid` for a value out of range (a negative seek, a speed outside 0.05–10) or a control while nothing is open, `unsupported` for something the source cannot do (a loop on a source that cannot seek).
+
+#### Open a file and follow it
+
+`open` resolves once the player accepted the load (for an address a resolver plugin handles, once the resolver has answered) and returns a `Media` handle for that source. `ready()` waits until it plays; `onEnd` fires when it ends on its own.
+
+```ts
+const media = await plugin.player.open("/Movies/clip.mp4");
+try {
+  await media.ready({ signal: AbortSignal.timeout(10_000) }); // closes it on timeout
+} catch (error) {
+  await plugin.osd.show("Cannot play: {}", [(error as Error).message]);
+}
+media.onEnd((ended) =>
+  // Play on only if nobody opened something else at the end.
+  plugin.player.open("/Movies/next.mp4", { ifCurrent: ended }).catch(() => {}),
+);
+```
+
+`ready()` rejects with `failed` (the file cannot be loaded), `replaced` (another source took over) or `ended`. Disposing your scope does not close the media: playback belongs to the user, so call `media.close()` when you mean it.
+
+#### Behave exactly like the player's own keys
+
+For buttons in your own bar or window, prefer the player's core actions to calling the controls yourself. `plugin.host.run` (capability `commands`) runs them with the player's checks, accumulation of repeated presses and on-screen text:
+
+```ts
+declare const bar: Panel;
+// ---cut---
+bar.on("playPause", () => plugin.host.run("play-pause"));
+bar.on("forward30", () => plugin.host.run("seek-forward", { seconds: 30 })); // adds up with →
+```
+
+`run` rejects with `unavailable` while the action is disabled, for example with nothing open.
+
+#### 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 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[];
+let index = 0;
+// ---cut---
+const playAt = async (at: number) => {
+  index = at;
+  await plugin.player.open(items[at]!);
+};
+plugin.player.provideSequence({
+  next: () => playAt(index + 1),
+  previous: () => playAt(index - 1),
+  canNext: () => index + 1 < items.length, // shown as state.can.next
+  canPrevious: () => index > 0,
+});
+```
+
+A second provider is refused with `conflict` (`sequence-taken`). During activation that does not fail the plugin: it runs without Next and Previous and the player shows a warning; a refusal after activation goes to `onError`.
+
+#### Sliders, loops and the output
+
+- A seek slider: start a `player.scrub()` gesture on press and `end()` it on release; see Keep a slider responsive while dragging.
+- An A-B loop: `setLoop({ a, b, count })`; `null` stops it, a new source clears it.
+- Volume and mute: `setOutput({ volume, muted })` (volume 0–200). The newest write wins; the promise resolves `false` when a newer one replaced it.
+- Your own step size for ← and →: `setStepSeek({ seconds, keyframes })`, withdrawn when your plugin stops.
+
+## How-to: Store a plugin's data
+
+**Goal:** your plugin keeps its settings across restarts, keeps work in progress across a reload, and keeps an API token safe, each in the right place.
+
+| What | Where | Lasts | Capability |
+| --- | --- | --- | --- |
+| Settings, history, small state | `plugin.storage.json(name)`: a JSON file in the data directory | Across player restarts and plugin upgrades | none |
+| Work in progress for this run | `plugin.storage.session`: values in the player's memory | Across plugin restarts (reload, crash, upgrade); cleared when the player quits or the plugin is disabled or uninstalled | none |
+| Tokens, passwords | `plugin.secrets`: the system's keychain or Credential Manager | Until deleted, or until the plugin is uninstalled with its data | `secrets` |
+| Anything else (caches, downloads) | Your own files under `plugin.dataDirectory` | Until you delete them | none |
+
+All four are private to the plugin; another plugin never reads them.
+
+#### Settings: a JSON file
+
+`storage.json` reads `<dataDirectory>/<name>.json` when you call it and gives you `value` at once (the defaults when the file is missing, broken or fails `validate`; a broken file is kept aside as `<name>.json.bad-<time>`). `save` replaces the value in memory and writes the file 300 ms later, through a temporary file and a rename.
+
+```ts
+type Prefs = { step: number; recent: string[] };
+const prefs = plugin.storage.json<Prefs>("prefs", {
+  defaults: { step: 5, recent: [] },
+  // Checked when the file is read: an older version may have written it.
+  validate: (v): v is Prefs => typeof (v as Prefs)?.step === "number" && Array.isArray((v as Prefs)?.recent),
+});
+prefs.save({ ...prefs.value, step: 10 }); // never change prefs.value in place
+```
+
+Stopping the plugin writes a pending save first, but only within the short time the player gives a stopping plugin (about 300 ms for a plugin in its own process), and a crash loses it; call `await prefs.flush()` after a save that must not be lost. Also flush before you read or copy the file yourself. See Remember a window's state between runs for a complete window built on a store.
+
+#### Work in progress: session values
+
+`storage.session` keeps JSON values in the player for this run: a reload of the plugin (an upgrade, a crash, the user's Reload) finds them again; the next player start does not.
+
+```ts
+const session = plugin.storage.session;
+const queue = (await session.get<string[]>("queue")) ?? []; // undefined: nothing stored
+queue.push("https://example.com/a.mkv");
+try {
+  await session.set("queue", queue); // kept once this resolves
+} catch (error) {
+  // `limit`: the plugin's values would pass 1 MiB; nothing changed.
+  if ((error as PluginError).code !== "limit") throw error;
+}
+```
+
+Each call is one request, answered in order, with no debounce. Keys are 1–1024 bytes; values come back as `JSON.stringify` wrote them (object properties may come back in another order, a `Date` as a string), and are not checked, so check their shape.
+
+#### Secrets: the system's store
+
+`plugin.secrets` stores short text values in the macOS keychain or the Windows Credential Manager. Never write a token to a settings file.
+
+```ts
+let token = await plugin.secrets.get("api-token").catch(() => null); // no store: ask
+if (token === null) {
+  token = "…"; // ask the user, for example in a tool window
+  await plugin.secrets.set("api-token", token).catch((error: PluginError) => {
+    // `unsupported` (no store), `unavailable` (store unreachable), `failed` (access denied).
+    void plugin.osd.show("The token is not kept for next time ({})", [error.code]);
+  });
+}
+```
+
+Names are 1–64 of `a-z 0-9 . _ -`, values 1–1024 bytes, at most 256 names. Have a fallback: some systems have no store, a store can be unreachable (no keychain, read-only, no logged-in session on Windows), and the user can deny access.
+
+#### Your own files
+
+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.
+
+```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.
@@ -3297,9 +3573,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>;
 }
 ```
@@ -3325,7 +3624,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). |
@@ -3345,7 +3643,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. |
@@ -3408,6 +3706,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`). */
@@ -3431,10 +3737,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). */
@@ -3488,17 +3800,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
@@ -3517,6 +3869,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
@@ -3536,6 +3889,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;
 }
@@ -3584,6 +3954,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"`. */
@@ -3889,12 +4265,23 @@ interface CommandOptions {
 A registered command, from Commands.add. Disposing it removes it
 from the menu and the binding table; the id can be added again right away.
 
+The handle of one menu item and its keys. Its state (`enabled`, `checked`,
+`busy`, `reason`) is bound: functions given to Commands.add or
+Command.set are evaluated again in every update pass and only
+changes reach the player. Its title, path, bindings and button cannot
+change in place; dispose the command (or a child Scope) and add it
+again. Disposing it, its scope or stopping the plugin removes the menu
+item, its keys and its bar button.
+
+- @capability commands
+
 ```ts
 interface Command extends Disposable {
   /** The local id given in CommandOptions.id. */
   readonly id: string;
   /**
    * Replace some state fields (values or functions). Last write wins.
+   * @capability commands
    * @example Show a command as busy while it works
    * The Export item shows as busy with "Exporting…" as its reason while the
    * export runs, then returns to normal. `set` replaces only the fields it
@@ -3920,15 +4307,47 @@ interface Command extends Disposable {
   }>): void;
   /**
    * Resolves when the host has registered the command. Rejects with `conflict` (path already taken), `invalid` or `limit` (more than 160 commands in this plugin, or 1024 in the whole player). You rarely need to await it: during activation a failure fails activation, later it goes to Scope.onError.
+   * @throws conflict (rejects) Another command already has this menu path, or the path would be both a menu item and a submenu.
+   * @throws capability (rejects) The manifest does not declare `commands`.
+   * @throws invalid (rejects) The player refused the declaration.
+   * @throws limit (rejects) More than 160 commands in this plugin, or 1024 in the player.
    */
   readonly ready: Promise<void>;
 }
 ```
 
+Example: Enable an item only while a file is open
+
+Video ▸ Export… is greyed out until a file is open. `set` replaces the
+`enabled` field with a function; the SDK evaluates it again after every
+player state change and sends the new state when it changes, so the
+item follows the player without further code.
+```ts
+const exportCommand = plugin.commands.add({
+  id: "export",
+  path: ["@video", "Export…"],
+  run: runExport,
+});
+// A function: re-evaluated in every update pass.
+exportCommand.set({ enabled: () => plugin.player.state.phase === "ready" });
+```
+
 ### Commands
 
 `plugin.commands`: menu commands with default bindings. Needs `commands`.
 
+A command is one action of the plugin with a menu item (`path`), default
+keys (`bindings`), optionally a bottom-bar button (`button`) and a state
+the menu shows (`enabled`, `checked`, `busy`, `reason`). The player owns
+the menu, the binding table and the user's key overrides: it calls `run`
+when the user picks the item, presses a key or clicks the button.
+Commands of all plugins merge into the player's menus by their English
+path keys. Registration is asynchronous: `add` returns at once, and
+Command.ready reports the player's answer (during activation a
+refusal fails activation).
+
+- @capability commands
+
 ```ts
 interface Commands {
   /**
@@ -3938,6 +4357,7 @@ interface Commands {
    * Titles and paths cannot change in place: put changing items (track
    * lists, presets) in a child Scope and rebuild it.
    * @throws invalid synchronously for a malformed path (including an unknown `@` menu id), order, group or binding; `conflict` for an id this plugin has already declared and not disposed.
+   * @capability commands
    * @example Pause playback from a menu item
    * Playback ▸ Pause (and Ctrl+P) pauses and resumes, shows a check mark
    * while paused and is greyed out when nothing can be paused. The player
@@ -3960,6 +4380,20 @@ interface Commands {
 }
 ```
 
+Example: Add a menu item with a default key
+
+Tools ▸ Say hello, or Ctrl+H, shows a greeting. `add` declares the item;
+the player calls `run` when the user picks it or presses its key, and the
+user can change the key in the player's key settings.
+```ts
+plugin.commands.add({
+  id: "hello",
+  path: ["Tools", "Say hello"],
+  bindings: ["Ctrl+H"], // a default; the user may override it
+  run: () => plugin.osd.show("Hello"),
+});
+```
+
 ### ImageRef
 
 An image file for a Slint `image` property, made by Ui.image.
@@ -5532,6 +5966,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 {
   /**
@@ -5542,6 +5983,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;
@@ -5567,6 +6009,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`
@@ -6438,10 +6899,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`
@@ -6466,22 +6935,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).
@@ -6517,11 +7040,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
@@ -6533,6 +7073,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;
@@ -6545,10 +7097,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>;
   /**
@@ -6563,6 +7147,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
@@ -6626,9 +7217,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 and the displays, read when called (displays come and go). 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>;
 }
 ```
@@ -7071,29 +7682,100 @@ media.onEnd(async (ended) => {
 
 A source this plugin opened.
 
+A source this plugin opened with Player.open. It does not own
+the source: the user or another plugin can replace it at any time, and
+`current` then turns false. `ready` and `onEnd` follow the player state:
+with `events` they react to the player's events, without it `ready`
+polls the state every 100 ms (which needs `playback.read`). Disposing the
+scope that opened it does not close the media; call `close` for that.
+
+- @capability That of Player.open (`playback.control`); `ready` and `onEnd` follow the state through `events` and `playback.read`.
+
 ```ts
 interface Media {
   /** Still the player's source (a restart keeps it current). */
   readonly current: boolean;
   /**
    * Resolves when it is playing. Rejects with code `failed` (load error), `replaced` (another source took over) or `ended`; with `AbortError` when the signal aborts, after closing the media.
+   * @capability That of Player.open; `playback.read` or `events` to see the state change.
+   * @throws failed (rejects) The media could not be loaded.
+   * @throws replaced (rejects) Another source took over first.
+   * @throws ended (rejects) The media already played to the end.
+   * @throws aborted (rejects) `signal` aborted (an `AbortError`); the media is closed.
+   * @example Wait at most ten seconds for a stream to start
+   * A network stream gets ten seconds to start playing; otherwise it is
+   * closed and the user is told. Aborting the signal makes `ready` reject
+   * with an `AbortError` after closing the media.
+   * ```ts
+   * const media = await plugin.player.open("https://example.com/live.m3u8");
+   * // The timeout's abort closes the media and rejects with an AbortError.
+   * try {
+   *   await media.ready({ signal: AbortSignal.timeout(10_000) });
+   * } catch (error) {
+   *   await plugin.osd.show("Not playing: {}", [(error as Error).message]);
+   * }
+   * ```
    */
   ready(options?: {
     signal?: AbortSignal;
   }): Promise<void>;
-  /** Called once each time a playthrough of this media ends naturally. */
+  /**
+   * Called once each time a playthrough of this media ends naturally.
+   * @capability That of Player.open; `events` to hear the end.
+   * @example Play the next file when this one ends
+   * When the plugin's file ends naturally, the next one opens. The listener
+   * gets the state at the end; passing it as `ifCurrent` makes the next
+   * `open` fail with `stale` (and do nothing) if the user opened something
+   * else in the meantime.
+   * ```ts
+   * media.onEnd((ended) =>
+   *   plugin.player.open(next, { ifCurrent: ended }).catch((error: PluginError) => {
+   *     if (error.code !== "stale") throw error; // the user opened something else
+   *   }),
+   * );
+   * ```
+   */
   onEnd(listener: (state: PlayerState) => void): Disposable;
-  /** Close it if it is still the player's source; otherwise do nothing. */
+  /**
+   * Close it if it is still the player's source; otherwise do nothing.
+   * @capability That of Player.open (`playback.control`).
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Close the preview the plugin opened
+   * The plugin closes the preview it opened, but leaves alone anything the
+   * user opened since. `close` acts only while this media is still the
+   * player's source and does nothing otherwise.
+   * ```ts
+   * await preview.close(); // a no-op when something else is playing now
+   * ```
+   */
   close(): Promise<void>;
 }
 ```
 
+Example: Open a file and say when it ends
+
+The file opens and plays, and the OSD says "Finished" when it reaches its
+end on its own. The handle belongs to this source: `onEnd` fires only
+for a natural end of this media, not when someone opens another file.
+```ts
+const media = await plugin.player.open("/Movies/clip.mp4");
+media.onEnd(() => void plugin.osd.show("Finished")); // natural ends only
+```
+
 ### Scrub
 
 A drag gesture: each seek is conditional on the previous one, latest value wins.
 Any outside change (another plugin opens a file, the user pauses) ends
 the gesture.
 
+A drag gesture on a seek slider. Each `seek` is conditional on the
+previous one and only the newest target is sent while a seek is
+running, so a fast drag never queues seeks. Any outside change (another
+file, the user pausing) ends the gesture: `active` turns false and later
+seeks resolve `false`.
+
+- @capability playback.control
+
 ```ts
 interface Scrub {
   /**
@@ -7113,6 +7795,11 @@ interface Scrub {
    * the target of a keyframe seek is always sent. Omitted or `false`: exact,
    * as before. Older players ignore the option and seek exactly: set
    * `"minPlayerVersion": "0.5.3"` when you rely on it.
+   * @capability playback.control
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @throws stale (rejects) The source changed from outside while this seek was being sent (a superseded target or an ended gesture resolves `false` instead).
+   * @throws unsupported (rejects) The source is a generated stream.
+   * @throws backend (rejects) The player failed the seek.
    * @example Scrub on keyframes for a fast picture
    * While dragging, the picture jumps to the nearest earlier keyframe at
    * once instead of decoding up to the exact frame. With `keyframes: true`
@@ -7128,7 +7815,17 @@ interface Scrub {
   }): Promise<boolean>;
   /** False once anyone else changed the source; later seeks are ignored. */
   readonly active: boolean;
-  /** End the gesture; later seeks resolve `false`. */
+  /**
+   * End the gesture; later seeks resolve `false`.
+   * @capability playback.control
+   * @example End the gesture when the user lets go
+   * Releasing the slider ends the gesture, so a late `dragMove` cannot move
+   * playback any more. After `end`, `seek` resolves `false` without doing
+   * anything.
+   * ```ts
+   * bar.on("dragEnd", () => scrub.end()); // later seeks resolve false
+   * ```
+   */
   end(): void;
 }
 ```
@@ -7206,6 +7903,15 @@ type StreamStartError = PluginError & {
 
 A generated source, from Player.openStream. Disposing it stops it.
 
+A source whose frames this plugin generates, from
+Player.openStream. The SDK pulls frames on the audio clock over
+a local connection and handles prefill, activation and pausing; the plugin
+only supplies `frame()`. A stream ends when the plugin stops it, when
+another source replaces it or the user closes it (`onStop` with `null`),
+or when it fails (`onStop` with the error).
+
+- @capability producer.av and playback.control
+
 ```ts
 interface Stream extends Disposable {
   /** The stream is producing frames. */
@@ -7222,15 +7928,51 @@ interface Stream extends Disposable {
    * (before 1.5.7 a replaced or closed stream could get `unavailable`
    * "producer absent"). Without `playback.read` a failure the SDK has not
    * seen yet is reported as null.
+   * @capability producer.av
+   * @example Tell the user why the stream stopped
+   * The OSD explains a failure, and nothing is said when the user simply
+   * opened another file. The listener runs only for stops from outside the
+   * plugin: `null` for a replacement or the user's close, an error (such as
+   * `stream` with the player's text) for a failure.
+   * ```ts
+   * stream.onStop((error) => {
+   *   if (error) void plugin.osd.show("Generator stopped: {}", [error.message]);
+   * });
+   * ```
    */
   onStop(listener: (error: PluginError | null) => void): Disposable;
   /**
    * Stop producing and close the stream if it is still the player's source. The source closes first, then the frame connection, then the producer, so stopping never shows as a playback failure. `dispose()` and deactivation do the same.
+   * @capability producer.av and playback.control
+   * @throws Whatever code closing the player's source failed with (the frame connection and the producer are released either way). A stream that is no longer the source just resolves.
+   * @example Stop the stream when the plugin's window closes
+   * Closing the generator window stops the stream it feeds. `stop` closes
+   * the player's source if it is still this stream and then the frame
+   * connection; it resolves once both are closed.
+   * ```ts
+   * window.onClose(() => stream.stop());
+   * ```
    */
   stop(): Promise<void>;
 }
 ```
 
+Example: Stop the stream from a menu item
+
+A menu item ends the plugin's generated stream and closes it as the
+player's source. `stop` closes the source first and then the frame
+connection, so the user never sees a playback error; `onStop` is not
+called for the plugin's own stop.
+```ts
+// Enabled while the stream produces frames.
+plugin.commands.add({
+  id: "stop-generator",
+  path: ["@playback", "Stop generator"],
+  enabled: () => stream.running,
+  run: () => stream.stop(),
+});
+```
+
 ### SequenceProvider
 
 The plugin that owns "next / previous" (a playlist).
@@ -7337,15 +8079,67 @@ Capabilities: reading (`state` at start, `refresh`, `stats`, `chapters`,
 Controls are conditional (see Conditional): they fail with
 `stale` and do nothing when the source changed since the state you saw.
 
+`plugin.player` is the player's one source: what is open, its phase and
+position, and the controls. `state` is a snapshot the SDK keeps current
+from the player's events (with `events`) and refreshes after this
+plugin's own calls; `onChange` runs after it changed. Every control is
+conditional: it acts on the state the plugin last saw and fails with
+`stale` when the source changed meanwhile: another file, a close, or any
+pause, seek or speed change by the user or another plugin (see
+Conditional). The player keeps the source when a plugin stops;
+only the plugin's own handles (a stream, its sequence provider, its
+output device) are withdrawn.
+
+- @capability `playback.read` to read; `playback.control` to control; `events` to follow changes made elsewhere; `producer.av` for Player.openStream.
+
 ```ts
 interface Player {
   /** Latest state; always newer than anything delivered before. */
   readonly state: PlayerState;
-  /** The state changed (needs `events` for outside changes). */
+  /**
+   * The state changed (needs `events` for outside changes).
+   * @capability events (for changes made elsewhere; without it the listener runs only after this plugin's own calls)
+   * @example Show the position while it plays
+   * The OSD block shows the position, updated as playback moves. The SDK
+   * updates `player.state` from the player's events and then calls the
+   * listener with the new snapshot; the handler only reads it.
+   * ```ts
+   * const info = plugin.osd.panel();
+   * plugin.player.onChange((state) => {
+   *   // `position` is null while nothing is open.
+   *   info.set(state.position === null ? null : "{} s", [state.position?.toFixed(0) ?? ""]);
+   * });
+   * ```
+   */
   onChange(listener: (state: PlayerState) => void): Disposable;
-  /** Read the state from the player now (`playback.read`). */
+  /**
+   * Read the state from the player now (`playback.read`).
+   * @capability playback.read
+   * @throws capability (rejects) The manifest does not declare `playback.read`.
+   * @example Read the state before deciding
+   * A command reads the newest state from the player before acting, even
+   * without `events`. `refresh` asks the player and resolves with the new
+   * snapshot; `player.state` holds it afterwards.
+   * ```ts
+   * const state = await plugin.player.refresh();
+   * if (state.phase === "ready") await plugin.osd.show("{} s left", [((state.duration ?? 0) - (state.position ?? 0)).toFixed(0)]);
+   * ```
+   */
   refresh(): Promise<PlayerState>;
-  /** True if nothing changed the source since `state` was observed. */
+  /**
+   * True if nothing changed the source since `state` was observed.
+   * @capability None.
+   * @example Drop a result that arrives after the file changed
+   * A slow lookup for the current file is shown only if that file is still
+   * open. `isCurrent` compares the snapshot taken before the work with the
+   * SDK's newest state; it is false once the source changed in any way:
+   * another file, a close, or a pause, seek or speed change by anyone.
+   * ```ts
+   * const seen = plugin.player.state;
+   * const title = await lookUpTitle(seen.source ?? "");
+   * if (plugin.player.isCurrent(seen)) await plugin.osd.show("{}", [title]); // still the same file
+   * ```
+   */
   isCurrent(state: PlayerState): boolean;
   /**
    * Open a path or URL, replacing the current source (unless `ifCurrent` no
@@ -7356,6 +8150,25 @@ interface Player {
    * Resolver are resolved first, and so are local files of an
    * extension a file resolver claims (the source is then a stream that
    * plugin generates; `paused` reaches it).
+   * @capability playback.control
+   * @throws stale (rejects) `ifCurrent` no longer holds; nothing was opened.
+   * @throws replaced (rejects) Accepted, then another source took over before it finished (for example while a URL was still being resolved).
+   * @throws invalid (rejects) An empty `source`.
+   * @throws aborted (rejects) `signal` aborted (an `AbortError`); the source is closed if it was opened.
+   * @throws busy (rejects) The address needs a resolver plugin and the player is already resolving 32 addresses.
+   * @throws backend (rejects) A resolver plugin handled the address or file and failed (its message), or the resolution was cancelled or expired.
+   * @throws unsupported (rejects) The player refused what a resolver returned (for example split streams with different headers).
+   * @throws unavailable (rejects) The stream a file resolver prepared was not ready to play.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Open a file paused
+   * The file opens at its start without playing. `open` resolves once the
+   * player accepted the load and returns a Media handle for that
+   * source; `ready` then waits until it can play (here: until it is loaded
+   * and paused).
+   * ```ts
+   * const media = await plugin.player.open("/Movies/clip.mp4", { paused: true });
+   * await media.ready(); // rejects `failed` when the file cannot be loaded
+   * ```
    */
   open(source: string, options?: {
     paused?: boolean;
@@ -7372,6 +8185,13 @@ interface Player {
    * TCP with a token on Windows. Rejects with a StreamStartError
    * (`timeout`), `stream`, `device`, or `replaced` when another source
    * replaced it (or it was closed) before it ran.
+   * @capability producer.av and playback.control
+   * @throws timeout (rejects) A StreamStartError: the stream did not start in time.
+   * @throws stream (rejects) The player failed to start the stream.
+   * @throws device (rejects) The audio device was not ready.
+   * @throws replaced (rejects) Another source replaced it, or it was closed, before it ran.
+   * @throws invalid (rejects) Bad options (a size or a frame function).
+   * @throws aborted (rejects) `signal` aborted, or the scope was disposed, while the stream was starting (an `AbortError`).
    * @example Play pictures the plugin draws itself
    * The player shows a 320×240 picture the plugin renders, with silence as
    * its sound, as the current source. The SDK pulls frames on the audio
@@ -7392,25 +8212,143 @@ interface Player {
    * ```
    */
   openStream(options: StreamOptions): Promise<Stream>;
-  /** Pause or resume. */
+  /**
+   * Pause or resume.
+   * @capability playback.control
+   * @throws stale (rejects) The source changed since the state the call is based on (another file, a close, or any pause, seek or speed change by the user or another plugin); nothing was done.
+   * @throws invalid (rejects) Nothing is open.
+   * @throws busy (rejects) A generated stream is still handling a previous control.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Pause, but only the file the user was watching
+   * A "pause on lock" helper pauses the current file and does nothing when
+   * another file was opened in between. The call is conditional on
+   * `player.state` by default; `stale` means the source changed and the
+   * pause was not applied, which is the intended outcome here.
+   * ```ts
+   * try {
+   *   await plugin.player.setPaused(true);
+   * } catch (error) {
+   *   if ((error as PluginError).code !== "stale") throw error; // another file now
+   * }
+   * ```
+   */
   setPaused(paused: boolean, options?: Conditional): Promise<void>;
-  /** Jump to `seconds`. */
+  /**
+   * Jump to `seconds`.
+   * @capability playback.control
+   * @throws stale (rejects) The source changed since the state the call is based on (another file, a close, or any pause, seek or speed change by the user or another plugin); nothing was done.
+   * @throws invalid (rejects) Nothing is open, or `seconds` is negative or not finite.
+   * @throws unsupported (rejects) The source is a generated stream, which cannot seek.
+   * @throws busy (rejects) A generated stream is still handling a previous control.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Jump back ten seconds
+   * Playback jumps ten seconds back, never before the start. The target is
+   * computed from the snapshot the call is conditional on, so if the user
+   * opened another file meanwhile the seek fails with `stale` instead of
+   * landing in the wrong file.
+   * ```ts
+   * const { position } = plugin.player.state;
+   * if (position !== null && plugin.player.state.can.seek)
+   *   await plugin.player.seek(Math.max(0, position - 10)); // seconds
+   * ```
+   */
   seek(seconds: number, options?: Conditional): Promise<void>;
-  /** Set the playback speed. */
+  /**
+   * Set the playback speed.
+   * @capability playback.control
+   * @throws stale (rejects) The source changed since the state the call is based on (another file, a close, or any pause, seek or speed change by the user or another plugin); nothing was done.
+   * @throws invalid (rejects) Nothing is open, or `rate` is outside 0.05–10.
+   * @throws unsupported (rejects) The source is a generated stream, which cannot change speed.
+   * @throws busy (rejects) A generated stream is still handling a previous control.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Play at one and a half times the speed
+   * Playback speeds up to 1.5×, with the speed on the OSD. `setRate` sets
+   * the speed directly (the player's own keys step it by 0.1 within
+   * 0.25–4); `state.can.rate` is false for sources that cannot change speed.
+   * ```ts
+   * if (plugin.player.state.can.rate) {
+   *   await plugin.player.setRate(1.5);
+   *   await plugin.osd.show("Speed {}×", [1.5]);
+   * }
+   * ```
+   */
   setRate(rate: number, options?: Conditional): Promise<void>;
-  /** Play from the start (the "replay" after the end). */
+  /**
+   * Play from the start (the "replay" after the end).
+   * @capability playback.control
+   * @throws stale (rejects) The source changed since the state the call is based on (another file, a close, or any pause, seek or speed change by the user or another plugin); nothing was done.
+   * @throws invalid (rejects) Nothing is open.
+   * @throws unsupported (rejects) The source is a generated stream, which cannot restart.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Replay a file after it ended
+   * A Replay button starts the file again from its start once it has ended.
+   * `restart` plays the current source from the beginning and keeps it the
+   * same source, so a Media handle stays current.
+   * ```ts
+   * if (plugin.player.state.phase === "ended") await plugin.player.restart();
+   * ```
+   */
   restart(options?: Conditional): Promise<void>;
-  /** Close the current source. */
+  /**
+   * Close the current source.
+   * @capability playback.control
+   * @throws stale (rejects) The source changed since the state the call is based on (another file, a close, or any pause, seek or speed change by the user or another plugin); nothing was done.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Close the file when the sleep timer runs out
+   * After 30 minutes the open file is closed, unless the user opened another
+   * one meanwhile. The snapshot taken when the timer started is passed as
+   * `ifCurrent`, so the close applies only to that source; `stale` means it
+   * was replaced.
+   * ```ts
+   * const seen = plugin.player.state;
+   * setTimeout(() => {
+   *   // Only the source that was open when the timer started.
+   *   plugin.player.close({ ifCurrent: seen }).catch((error: PluginError) => {
+   *     if (error.code !== "stale") plugin.osd.show("Could not close: {}", [error.code]);
+   *   });
+   * }, 30 * 60 * 1000);
+   * ```
+   */
   close(options?: Conditional): Promise<void>;
-  /** Start a drag gesture from the current state. */
+  /**
+   * Start a drag gesture from the current state.
+   * @capability playback.control
+   * @example Start a gesture when the user grabs the slider
+   * A drag on the plugin's seek slider becomes one gesture whose seeks never
+   * pile up. `scrub()` captures the current state; the gesture's seeks are
+   * conditional on it and on each other, and it ends on its own when
+   * someone else changes the source.
+   * ```ts
+   * let scrub: Scrub | null = null;
+   * bar.on("dragStart", () => (scrub = plugin.player.scrub()));
+   * bar.on("dragEnd", () => scrub?.end());
+   * ```
+   */
   scrub(): Scrub;
-  /** Device output; last write wins and volume is applied before mute. Resolves `true` when this request was applied, `false` if superseded. `volume` is 0–200. */
+  /**
+   * Device output; last write wins and volume is applied before mute. Resolves `true` when this request was applied, `false` if superseded. `volume` is 0–200.
+   * @capability playback.control
+   * @throws invalid (rejects) `volume` outside 0–200, or `muted` not a boolean.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Duck the volume during an announcement
+   * The volume drops to 30 while the plugin's announcement plays, then
+   * returns. Writes are "latest wins": the promise resolves `true` when this
+   * write was applied and `false` when a newer one replaced it first, which
+   * is not an error.
+   * ```ts
+   * const before = plugin.player.state.volume; // 0–200
+   * await plugin.player.setOutput({ volume: 30 });
+   * // … the announcement …
+   * await plugin.player.setOutput({ volume: before });
+   * ```
+   */
   setOutput(output: {
     volume?: number;
     muted?: boolean;
   }): Promise<boolean>;
   /**
-   * Become the sequence provider (one at a time; another provider rejects with `conflict` through the scope's `onError`, or fails activation). Dispose to stop.
+   * Become the sequence provider, first come first served: while another plugin holds it (the built-in playlist registers at activation), this one is refused with `conflict` (`sequence-taken`). That does not fail activation: the player shows a warning (PluginInfo.warnings); a refusal after activation goes to the scope's `onError`. Dispose to stop.
+   * @capability playback.control
    * @example Drive the player's Next and Previous from a playlist
    * The player's Next and Previous items and keys play the plugin's list.
    * The player calls `next` and `previous` when the user asks; `canNext`
@@ -7432,19 +8370,99 @@ interface Player {
    * ```
    */
   provideSequence(provider: SequenceProvider): Disposable;
-  /** Ask the provider to go forward / back. Rejects `unavailable` when it cannot. */
+  /**
+   * Ask the provider to go forward / back. Rejects `unavailable` when it cannot.
+   * @capability playback.control
+   * @throws unavailable (rejects) There is no sequence provider, or it has no next item.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Skip to the next item from a plugin button
+   * The plugin's own Next button plays the next item of whichever plugin
+   * provides the sequence (the playlist, usually). `next` asks the
+   * provider, the same as the player's Next key; `unavailable` means there
+   * is no next item, which the button treats as the end of the list.
+   * ```ts
+   * try {
+   *   await plugin.player.next(); // as the player's Next key does
+   * } catch (error) {
+   *   if ((error as PluginError).code !== "unavailable") throw error;
+   *   await plugin.osd.show("End of the list");
+   * }
+   * ```
+   */
   next(): Promise<void>;
-  /** Ask the provider to go back. Rejects `unavailable` when it cannot. */
+  /**
+   * Ask the provider to go back. Rejects `unavailable` when it cannot.
+   * @capability playback.control
+   * @throws unavailable (rejects) There is no sequence provider, or it has no previous item.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Go back to the previous item
+   * The plugin's Previous button asks the sequence provider for the item
+   * before the current one, like the player's PageUp. It is disabled while
+   * `state.can.previous` is false, which the provider's `canPrevious`
+   * decides.
+   * ```ts
+   * plugin.commands.add({
+   *   id: "previous",
+   *   title: "Previous item",
+   *   // The provider's `canPrevious`, as the player reports it.
+   *   enabled: () => plugin.player.state.can.previous,
+   *   run: () => plugin.player.previous(),
+   * });
+   * ```
+   */
   previous(): Promise<void>;
-  /** Codec, size, frame counts and backend of the current playback. `playback.read`; `video` and `audio` are `null` without a source. */
+  /**
+   * Codec, size, frame counts and backend of the current playback. `playback.read`; `video` and `audio` are `null` without a source.
+   * @capability playback.read
+   * @throws capability (rejects) The manifest does not declare `playback.read`.
+   * @example Show the video codec and size
+   * The OSD shows something like "h264 1920×1080". `stats` asks the player
+   * for the backend's own values at that moment; `video` is `null` without
+   * a video stream (nothing open, an audio file).
+   * ```ts
+   * const { video } = await plugin.player.stats();
+   * if (video) await plugin.osd.show("{} {}×{}", [video.codec ?? "?", video.width ?? 0, video.height ?? 0]);
+   * ```
+   */
   stats(): Promise<PlaybackStats>;
   /**
    * Add an external audio file (absolute local path) to the current media and, unless `select: false`, select it. Resolves with the new track (`external`, not exportable). It stays until the source changes. Rejects `invalid` for a bad path, `unavailable` without ready media, `backend` when it cannot load.
+   * @capability playback.control
+   * @throws invalid (rejects) Not an absolute path to a file.
+   * @throws unavailable (rejects) No ready media.
+   * @throws backend (rejects) The player could not load the file.
+   * @throws stale (rejects) `ifCurrent` no longer holds.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Add a dubbed audio file and switch to it
+   * A separate audio file plays with the film instead of its own sound.
+   * `addAudioTrack` attaches the file to the current media and selects it;
+   * the track stays until another source opens.
+   * ```ts
+   * const track = await plugin.player.addAudioTrack(dubPath); // selected too
+   * await plugin.osd.show("Audio: {}", [track.title ?? dubPath]);
+   * ```
    */
   addAudioTrack(path: string, options?: {
     select?: boolean;
   } & Conditional): Promise<AudioTrack>;
-  /** Select one of `state.audioTracks` by id; `invalid` for an unknown id. */
+  /**
+   * Select one of `state.audioTracks` by id; `invalid` for an unknown id.
+   * @capability playback.control
+   * @throws invalid (rejects) No track with this id.
+   * @throws unavailable (rejects) No ready media.
+   * @throws stale (rejects) The source changed since the state the call is based on (another file, a close, or any pause, seek or speed change by the user or another plugin).
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Switch to the next audio track
+   * Each press of the plugin's key moves to the next audio track of the
+   * file. The tracks and the selected one are in `state.audioTracks`;
+   * `selectAudioTrack` resolves with the new state.
+   * ```ts
+   * const audioTracks = plugin.player.state.audioTracks ?? []; // null: not known yet
+   * const at = audioTracks.findIndex((track) => track.selected);
+   * const next = audioTracks[(at + 1) % audioTracks.length];
+   * if (next) await plugin.player.selectAudioTrack(next.id);
+   * ```
+   */
   selectAudioTrack(id: number, options?: Conditional): Promise<PlayerState>;
   /**
    * One frame or to the next / previous keyframe (pauses for frames). Rejects
@@ -7454,6 +8472,19 @@ interface Player {
    * Resolves once the new position is in effect, so `player.state.position`
    * is current afterwards. One step at a time: a second call while one is
    * in flight rejects `busy`.
+   * @capability playback.control
+   * @throws unsupported (rejects) Nothing playable to step through (no moving video: audio only, cover art, a generated stream), a backward frame step on a source that cannot seek, or a keyframe step in either direction on a source that cannot seek.
+   * @throws busy (rejects) A step is still in flight.
+   * @throws stale (rejects) The source changed since the state the call is based on (another file, a close, or any pause, seek or speed change by the user or another plugin).
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Step one frame forward for a close look
+   * The picture advances by one frame and playback pauses. `step` resolves
+   * once the new position is in effect, so `state.position` is current
+   * afterwards; a second step while one is running rejects with `busy`.
+   * ```ts
+   * await plugin.player.step("frame", "forward");
+   * await plugin.osd.show("{} s", [plugin.player.state.position?.toFixed(3) ?? "?"]);
+   * ```
    */
   step(unit: "frame" | "keyframe", direction: "backward" | "forward", options?: Conditional): Promise<void>;
   /**
@@ -7476,12 +8507,37 @@ interface Player {
    *
    * Older players ignore `keyframes`: set `"minPlayerVersion": "0.5.1"` in
    * the manifest when you rely on it.
+   * @capability playback.control
+   * @throws invalid (rejects) `seconds` outside 0.1–3600 or not in tenths, or `keyframes` not a boolean.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Make ← and → jump 10 seconds to keyframes
+   * The arrow keys now jump 10 seconds and land on keyframes, which is fast
+   * on large files. The newest call of any plugin wins and is withdrawn
+   * when that plugin stops, so a plugin offering this as a setting applies
+   * it on activation.
+   * ```ts
+   * await plugin.player.setStepSeek({ seconds: 10, keyframes: true });
+   * ```
    */
   setStepSeek(options: {
     seconds: number;
     keyframes?: boolean;
   }): Promise<void>;
-  /** The chapters of the current media (empty without media or chapters), read on demand; `sourceId` tells which source they belong to. `playback.read`. */
+  /**
+   * The chapters of the current media (empty without media or chapters), read on demand; `sourceId` tells which source they belong to. `playback.read`.
+   * @capability playback.read
+   * @throws capability (rejects) The manifest does not declare `playback.read`.
+   * @example List the chapters of the open file
+   * The plugin reads the chapter titles of the current file to show them in
+   * its panel. `chapters` asks the player when called; `sourceId` says which
+   * source they belong to, so a reply for a file that was replaced meanwhile
+   * can be dropped.
+   * ```ts
+   * const { sourceId, chapters } = await plugin.player.chapters();
+   * if (sourceId === plugin.player.state.sourceId) // still the same file
+   *   console.log(chapters.map((chapter) => chapter.title));
+   * ```
+   */
   chapters(): Promise<{
     /** The source the chapters belong to (compare with `state.sourceId`). */
     sourceId: number;
@@ -7490,13 +8546,45 @@ interface Player {
   }>;
   /**
    * A-B loop: on reaching `b`, jump back to `a` (seconds, `0 ≤ a < b ≤ duration`), `count` times (positive integer; omitted = endless); `null` stops it. After the last jump back `state.loop` becomes null. `invalid` out of range, `unsupported` for a source that cannot seek, `unavailable` without ready media. A new source clears it.
+   * @capability playback.control
+   * @throws invalid (rejects) `a`/`b` out of range or `count` not a positive integer.
+   * @throws unsupported (rejects) The source cannot seek, or is a generated stream.
+   * @throws unavailable (rejects) No ready media.
+   * @throws stale (rejects) The source changed since the state the call is based on (another file, a close, or any pause, seek or speed change by the user or another plugin).
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Loop a passage three times
+   * Playback repeats 1:00–1:30 three times, then goes on. The player jumps
+   * back to `a` each time it reaches `b`; after the last repeat
+   * `state.loop` becomes `null`, and a new source clears the loop.
+   * ```ts
+   * await plugin.player.setLoop({ a: 60, b: 90, count: 3 }); // seconds
+   * ```
    */
   setLoop(loop: {
     a: number;
     b: number;
     count?: number;
   } | null, options?: Conditional): Promise<void>;
-  /** The output devices present now (not the system default entry). `playback.read`. */
+  /**
+   * The output devices present now (not the system default entry). `playback.read`.
+   * @capability playback.read
+   * @throws capability (rejects) The manifest does not declare `playback.read`.
+   * @example Offer the audio output devices in a menu
+   * A submenu lists the output devices present now, with a radio mark on the
+   * one in use. `audioDevices` asks the player when called (devices come and
+   * go), and `state.audioOutput` tells which one is active.
+   * ```ts
+   * // The devices present now; build the menu again when they change.
+   * for (const device of await plugin.player.audioDevices())
+   *   plugin.commands.add({
+   *     id: `device.${device.id}`,
+   *     path: ["@audio", "Output", device.name],
+   *     radio: true,
+   *     checked: () => plugin.player.state.audioOutput?.active === device.id,
+   *     run: () => plugin.player.setAudioDevice(device.id),
+   *   });
+   * ```
+   */
   audioDevices(): Promise<AudioDevice[]>;
   /**
    * Play on this device while it is present, else on the system default
@@ -7506,6 +8594,18 @@ interface Player {
    * Unknown ids are accepted (`state.audioOutput.active` stays `null`); a
    * malformed id is `invalid`. Reverts to the default when this plugin
    * stops; save the choice yourself to restore it on activation.
+   * @capability playback.control
+   * @throws invalid (rejects) A malformed id.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Restore the user's output device on start
+   * The plugin plays on the device the user picked last time, or on the
+   * system default when it is not connected. The choice lasts only for
+   * this run and is withdrawn when the plugin stops, so the plugin saves
+   * it itself and sets it again on activation.
+   * ```ts
+   * const store = plugin.storage.json("output", { defaults: { device: null as string | null } });
+   * await plugin.player.setAudioDevice(store.value.device); // null: the system default
+   * ```
    */
   setAudioDevice(id: string | null): Promise<void>;
 }
@@ -7558,6 +8658,15 @@ type HostAction = "play-pause" | "stop" | "previous" | "next" | "frame-back" | "
 
 `plugin.host`: the player's own core actions.
 
+The player's core actions (play/pause, stop, step seeks, speed, volume,
+fullscreen…) are commands of the player itself, `host/<action>` in the
+binding table. Running them through `host.run` gives a plugin's own
+buttons exactly the player's behaviour: the same checks, the same
+accumulation of repeated presses and the same on-screen text, instead of
+reimplementing them with Player calls.
+
+- @capability commands
+
 ```ts
 interface Host {
   /**
@@ -7567,6 +8676,10 @@ interface Host {
    * `invalid` for an unknown id. Needs `commands`.
    *
    * Prefer this over reimplementing playback buttons.
+   * @capability commands
+   * @throws unavailable (rejects) The action is disabled right now (nothing open, no window for `fullscreen`).
+   * @throws invalid (rejects) An unknown action, or `seconds` out of range.
+   * @throws capability (rejects) The manifest does not declare `commands`.
    * @example Make a bar button play and pause like Space
    * The plugin's own Play button behaves exactly like the player's Space
    * key, including its on-screen text. `host.run` runs the core action
@@ -7597,6 +8710,10 @@ interface Host {
    * once the seek is submitted, as before. `invalid` for `seconds` out of
    * range.
    * @player 0.5.1 (set `"minPlayerVersion": "0.5.1"`: older players ignore `seconds` and seek by the `setStepSeek` step)
+   * @capability commands
+   * @throws unavailable (rejects) The action is disabled right now (nothing open, no window for `fullscreen`).
+   * @throws invalid (rejects) An unknown action, or `seconds` out of range.
+   * @throws capability (rejects) The manifest does not declare `commands`.
    * @example Add a 30-second skip that adds up with the arrow keys
    * The plugin's "+30 s" button seeks forward 30 seconds and shows the same
    * text as →. Passing `seconds` makes the core step seek use that step
@@ -7612,6 +8729,21 @@ interface Host {
 }
 ```
 
+Example: Give a custom bar the player's own Stop and Mute
+
+The plugin's bar buttons stop playback and mute exactly as the player's
+own keys do, with the same on-screen text. Each callback runs a core
+action; the player applies its checks and rejects with `unavailable`
+while the action is disabled, which the bar ignores.
+```ts
+const run = (action: HostAction) =>
+  plugin.host.run(action).catch((error: PluginError) => {
+    if (error.code !== "unavailable") throw error; // disabled right now
+  });
+bar.on("stop", () => run("stop"));
+bar.on("mute", () => run("mute"));
+```
+
 ### OsdPanel
 
 This plugin's information block on the OSD: multi-line text over the
@@ -7835,6 +8967,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[]>;
 ```
@@ -7862,6 +9002,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. */
@@ -7912,13 +9058,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;
 }
 ```
@@ -7928,7 +9107,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" });
@@ -7966,13 +9145,45 @@ Platforms: only macOS renders on the GPU. Under software rendering
 `unsupported`. 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;
 }
 ```
@@ -8074,16 +9285,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";
@@ -8100,6 +9374,25 @@ 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.
+   * @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.
+   * @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";
@@ -8107,10 +9400,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>;
 }
@@ -8161,6 +9484,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. */
@@ -8182,11 +9513,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
@@ -8239,31 +9604,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>;
 }
@@ -8416,25 +9871,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;
   /**
@@ -8587,6 +10101,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. */
@@ -8599,11 +10122,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.
@@ -8617,21 +10167,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`).
@@ -8713,6 +10313,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 {
   /**
@@ -8723,18 +10331,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>;
   /**
@@ -8752,10 +10435,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;
@@ -8830,9 +10541,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[];
@@ -8846,11 +10579,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;
 }
 ```
@@ -8876,13 +10645,65 @@ PNG/JPEG bytes; Windows writes Unicode text and images as a bitmap plus
 PNG. Other systems: `unsupported`. Failures: `invalid`, `missing`,
 `unavailable`, `failed` (the system refused).
 
+The player reads and writes the system clipboard on the plugin's behalf.
+Text is plain text; images are written from a PNG or JPEG file.
+
+- @capability clipboard
+
 ```ts
 interface Clipboard {
-  /** Plain text on the clipboard; `null` when it holds none. */
+  /**
+   * Plain text on the clipboard; `null` when it holds none.
+   * @capability clipboard
+   * @throws unavailable (rejects) The player runs without a user interface.
+   * @throws unsupported (rejects) A system other than macOS and Windows.
+   * @throws failed (rejects) The system refused (Windows).
+   * @throws capability (rejects) The manifest does not declare `clipboard`.
+   * @example Open a URL the user copied
+   * A "Paste and play" command opens the address on the clipboard. `readText`
+   * resolves with the clipboard's text, or `null` when it holds none (an
+   * image, nothing).
+   * ```ts
+   * const text = await plugin.clipboard.readText();
+   * if (text?.startsWith("https://")) await plugin.player.open(text.trim());
+   * ```
+   */
   readText(): Promise<string | null>;
-  /** Replace the clipboard with text (at most 1 MiB of UTF-8). */
+  /**
+   * Replace the clipboard with text (at most 1 MiB of UTF-8).
+   * @capability clipboard
+   * @throws invalid (rejects) More than 1 MiB of UTF-8.
+   * @throws unavailable (rejects) The player runs without a user interface.
+   * @throws unsupported (rejects) A system other than macOS and Windows.
+   * @throws failed (rejects) The system refused.
+   * @throws capability (rejects) The manifest does not declare `clipboard`.
+   * @example Copy the playing file's path
+   * The path of the playing file is put on the clipboard, replacing what was
+   * there. It resolves once the system has it.
+   * ```ts
+   * const { source } = plugin.player.state;
+   * if (source) await plugin.clipboard.writeText(source);
+   * ```
+   */
   writeText(text: string): Promise<void>;
-  /** Replace the clipboard with a PNG or JPEG file (absolute path, at most 16 MB). */
+  /**
+   * Replace the clipboard with a PNG or JPEG file (absolute path, at most 16 MB).
+   * @capability clipboard
+   * @throws missing (rejects) The file does not exist.
+   * @throws invalid (rejects) Not an absolute path, not PNG or JPEG, over 16 MB, or (Windows) an image the system cannot decode.
+   * @throws unavailable (rejects) The player runs without a user interface.
+   * @throws unsupported (rejects) A system other than macOS and Windows.
+   * @throws failed (rejects) The system refused.
+   * @throws capability (rejects) The manifest does not declare `clipboard`.
+   * @example Copy a snapshot to the clipboard
+   * A frame the plugin saved as PNG is put on the clipboard, ready to paste
+   * into another application. The player reads the file and writes the
+   * image (macOS: its original bytes; Windows: a bitmap plus PNG).
+   * ```ts
+   * await plugin.clipboard.writeImage(pngPath); // absolute path, at most 16 MB
+   * await plugin.osd.show("Snapshot copied");
+   * ```
+   */
   writeImage(path: string): Promise<void>;
 }
 ```
@@ -8906,6 +10727,12 @@ try {
 
 Keeping the computer awake (`playback.control`).
 
+A request, not a command: the player keeps the system awake while any
+plugin asks for it and a source plays, and withdraws a plugin's request
+when it stops.
+
+- @capability playback.control
+
 ```ts
 interface Power {
   /**
@@ -8917,11 +10744,31 @@ interface Power {
    * take the system assertion are logged by the player, not reported.
    * macOS uses `caffeinate`, Windows the thread execution state; elsewhere
    * it has no effect.
+   * @capability playback.control
+   * @throws invalid (rejects) A mode other than `"off"` or `"playing"`.
+   * @throws capability (rejects) The manifest does not declare `playback.control`.
+   * @example Follow the plugin's own "Keep awake" setting
+   * The plugin keeps the display awake during playback only while its
+   * setting is on. Each call replaces this plugin's request; `"off"`
+   * withdraws it, and other plugins' requests still count.
+   * ```ts
+   * const store = plugin.storage.json("power", { defaults: { keepAwake: true } });
+   * await plugin.power.preventSleep(store.value.keepAwake ? "playing" : "off");
+   * ```
    */
   preventSleep(mode: "off" | "playing"): Promise<void>;
 }
 ```
 
+Example: Keep the display on while playing
+
+The screen does not dim or sleep while a video plays, and may again when
+it is paused or ends. The player takes the system's assertion only while
+a source is ready and not paused.
+```ts
+await plugin.power.preventSleep("playing"); // "off" withdraws the request
+```
+
 ### ToolResult
 
 The output of Tools.run.
@@ -8940,11 +10787,20 @@ interface ToolResult {
 `plugin.tools`: ffmpeg and ffprobe, run in this plugin's process. No
 capability.
 
+ffmpeg and ffprobe run as child processes of the plugin. When
+`VESTRA_FFMPEG` / `VESTRA_FFPROBE` is set, only that path is used (an
+invalid one means the tool is not found); otherwise the tool is searched
+on `PATH`. A found path is kept for the plugin's run, a miss is looked up
+again next time. Disposing the
+scope ends a running process.
+
+- @capability None.
+
 ```ts
 interface Tools {
   /**
-   * Run ffmpeg or ffprobe (found through `VESTRA_FFMPEG` / `VESTRA_FFPROBE`,
-   * then `PATH`) without a shell. Rejects `unavailable` (not found), `timeout`,
+   * Run ffmpeg or ffprobe (`VESTRA_FFMPEG` / `VESTRA_FFPROBE` when set, else
+   * found on `PATH`) without a shell. Rejects `unavailable` (not found), `timeout`,
    * `failed` (non-zero exit; `message` is the last stderr line), `invalid`
    * (output over `maxOutput`, default 16 MiB), `aborted` (`signal`). Timeout,
    * `signal` and disposing the scope end the process.
@@ -8952,13 +10808,50 @@ interface Tools {
    * Arguments are passed as-is (no quoting needed). On Windows `PATHEXT` is
    * honoured. Ending sends SIGTERM, then SIGKILL after 300 ms (immediate on
    * Windows).
+   * @capability None.
+   * @throws unavailable (rejects) The tool was not found.
+   * @throws timeout (rejects) It ran longer than `timeoutMs`; the process is ended.
+   * @throws failed (rejects) A non-zero exit; `message` is the last stderr line.
+   * @throws invalid (rejects) Bad arguments or options, or output over `maxOutput`.
+   * @throws aborted (rejects) `signal` aborted, or the scope was disposed.
+   * @example Cut a clip without re-encoding
+   * The plugin writes the first ten seconds of the file to a new file. `run`
+   * starts ffmpeg without a shell (arguments pass as they are, no quoting)
+   * and resolves with its output once it exits with 0; a failure rejects
+   * with the last line ffmpeg printed.
+   * ```ts
+   * await plugin.tools.run(
+   *   "ffmpeg",
+   *   ["-y", "-i", input, "-t", "10", "-c", "copy", output],
+   *   { timeoutMs: 60_000 }, // give up after a minute
+   * );
+   * ```
    */
   run(tool: "ffmpeg" | "ffprobe", args: string[], options: {
     timeoutMs: number;
     maxOutput?: number;
     signal?: AbortSignal;
   }): Promise<ToolResult>;
-  /** Whether the tool can be found. */
+  /**
+   * Whether the tool can be found.
+   * @capability None.
+   * @throws Never; it resolves `false` when the tool cannot be found.
+   * @example Grey out a command when ffmpeg is missing
+   * The Export item is disabled with a reason when ffmpeg is not installed.
+   * `available` looks the tool up (a found path is kept, a miss is looked
+   * up again on the next call, so installing it later is noticed).
+   * ```ts
+   * const hasFfmpeg = await plugin.tools.available("ffmpeg");
+   * plugin.commands.add({
+   *   id: "export",
+   *   path: ["@video", "Export…"],
+   *   enabled: hasFfmpeg,
+   *   // Shown with the greyed-out item.
+   *   reason: hasFfmpeg ? null : "Install ffmpeg to export",
+   *   run() {},
+   * });
+   * ```
+   */
   available(tool: "ffmpeg" | "ffprobe"): Promise<boolean>;
 }
 ```
@@ -8986,21 +10879,75 @@ if (await plugin.tools.available("ffprobe")) {
 
 A JSON file `dataDirectory/<name>.json`, loaded once and saved debounced.
 
+One JSON file, `<dataDirectory>/<name>.json`, made by
+Storage.json. `value` is read once when the store is made;
+`save` replaces it in memory at once and writes the file `debounceMs`
+later (300 by default) through a temporary file and a rename, so a
+crash never leaves half a file. Writes to one file run one at a time,
+newest last. Disposing the store, its scope or stopping the plugin
+writes a pending save first.
+
+- @capability None.
+
 ```ts
 interface JsonStore<T> extends Disposable {
   /** The loaded value, or `defaults` when the file was missing or broken. */
   readonly value: T;
-  /** Replace the value now and write it after `debounceMs`. Only `save` writes: mutating `value` in place is not saved. */
+  /**
+   * Replace the value now and write it after `debounceMs`. Only `save` writes: mutating `value` in place is not saved.
+   * @capability None.
+   * @example Save a slider value without writing on every move
+   * Dragging the plugin's volume slider updates the stored value at once but
+   * writes the file only once the user stops for 300 ms. Each `save`
+   * replaces the value and restarts the debounce timer.
+   * ```ts
+   * const store = plugin.storage.json("prefs", { defaults: { volume: 100 } });
+   * window.on("volumeChanged", (volume: number) => store.save({ ...store.value, volume }));
+   * ```
+   */
   save(next: T): void;
-  /** Write a pending save now. */
+  /**
+   * Write a pending save now.
+   * @capability None.
+   * @throws Error (rejects) Node's file system error when the file cannot be written; its `code` is Node's (`ENOSPC`, `EACCES` and so on), not a player error code.
+   * @example Write the file now before copying it
+   * Before exporting its settings, the plugin makes sure the file on disk has
+   * the latest value. `flush` writes a pending save at once (or waits for
+   * the write in progress) and resolves when the file is written.
+   * ```ts
+   * const store = plugin.storage.json("settings", { defaults: { step: 5 } });
+   * await store.flush(); // the file now has the newest value
+   * await copyFile(join(plugin.dataDirectory, "settings.json"), exportPath);
+   * ```
+   */
   flush(): Promise<void>;
 }
 ```
 
+Example: Count how often the plugin was started
+
+The counter grows by one at every start and is kept in `stats.json`. The
+store reads the file when it is made (the defaults when there is none),
+and `save` writes the new count a moment later.
+```ts
+const stats = plugin.storage.json("stats", { defaults: { starts: 0 } });
+stats.save({ starts: stats.value.starts + 1 }); // written 300 ms later
+```
+
 ### Storage
 
 `plugin.storage`: JSON settings files. No capability.
 
+Two kinds of storage, both private to the plugin and needing no
+capability. Storage.json keeps settings in JSON files in the
+plugin's data directory: they last across player restarts and upgrades,
+and are written by the plugin's own process. Storage.session
+keeps values in the player's memory for one player run: they survive a
+restart of the plugin's process but not of the player. Secrets belong in
+Secrets, never in either.
+
+- @capability None.
+
 ```ts
 interface Storage {
   /**
@@ -9011,6 +10958,8 @@ interface Storage {
    *
    * The file is read synchronously on creation; `debounceMs` defaults to
    * 300. Files are created with mode 0600. `invalid` for a bad name.
+   * @capability None.
+   * @throws invalid (throws) A bad `name`, or a `debounceMs` that is not a non-negative number.
    * @example Keep settings and a recent list in a JSON file
    * The plugin remembers whether to resume and the last ten files across
    * restarts. `json` reads `settings.json` from the data directory at once
@@ -9040,6 +10989,19 @@ interface Storage {
 }
 ```
 
+Example: Keep a setting across restarts and a queue for this run
+
+The plugin's step size survives a restart of the player; its work queue
+survives a reload of the plugin but starts empty with the next player
+run. The JSON store reads its file at once and writes it shortly after
+each `save`; session values live in the player process.
+```ts
+const settings = plugin.storage.json("settings", { defaults: { step: 5 } });
+const queue = (await plugin.storage.session.get<string[]>("queue")) ?? [];
+void settings.value.step; // read synchronously, from the file or the defaults
+void queue;
+```
+
 ### SessionStorage
 
 `plugin.storage.session`: JSON values that live as long as the **player**,
@@ -9085,17 +11047,74 @@ quitting).
   resolves, so a crash right after loses nothing; there is no debounce.
   Calls answer in order.
 
+The player keeps the values in its own memory, per plugin, until it
+quits; the plugin's process may restart in between. Each call is one
+request to the player, answered in order, with no debounce.
+
+- @capability None.
+
 ```ts
 interface SessionStorage {
-  /** The value stored under `key`, or `undefined` when there is none. */
+  /**
+   * The value stored under `key`, or `undefined` when there is none.
+   * @capability None.
+   * @throws invalid (rejects) A bad key (empty, over 1024 bytes, with NUL or a lone surrogate).
+   * @throws disabled (rejects) The plugin is stopping.
+   * @throws unsupported (rejects) A player before 0.5.5.
+   * @example Pick up where the plugin stopped after a reload
+   * After a reload the plugin resumes the item it was working on. `get`
+   * asks the player and resolves with the value parsed from JSON, or
+   * `undefined` when nothing is stored; the value is not checked, so its
+   * shape is checked here.
+   * ```ts
+   * const current = await plugin.storage.session.get<{ url: string }>("current");
+   * if (typeof current?.url === "string") await plugin.osd.show("Resuming {}", [current.url]);
+   * ```
+   */
   get<T = unknown>(key: string): Promise<T | undefined>;
   /**
    * Store or replace `value` under `key`. `invalid` for a bad key or a value that is not JSON, `limit` when the plugin's values would be over 1 MiB or the request over the 1 MiB message limit.
+   * @capability None.
+   * @throws invalid (rejects) A bad key, or a value JSON cannot hold (or a string with a lone surrogate).
+   * @throws disabled (rejects) The plugin is stopping.
+   * @throws unsupported (rejects) A player before 0.5.5.
+   * @throws limit (rejects) The plugin's values would pass 1 MiB, or the request the 1 MiB message limit; nothing changes.
+   * @example Remember the item being worked on
+   * The plugin records the URL it is processing, so a reload can continue
+   * with it. The value is stored as `JSON.stringify` writes it, and is kept
+   * once the promise resolves.
+   * ```ts
+   * await plugin.storage.session.set("current", { url: "https://example.com/a.mkv" });
+   * ```
    */
   set(key: string, value: unknown): Promise<void>;
-  /** Remove a key; removing a missing one is fine. */
+  /**
+   * Remove a key; removing a missing one is fine.
+   * @capability None.
+   * @throws invalid (rejects) A bad key.
+   * @throws disabled (rejects) The plugin is stopping.
+   * @throws unsupported (rejects) A player before 0.5.5.
+   * @example Forget the item once it is done
+   * When the work finishes, the plugin removes the entry so that a later
+   * reload does not resume it. Removing a key that is not there is fine.
+   * ```ts
+   * await plugin.storage.session.delete("current");
+   * ```
+   */
   delete(key: string): Promise<void>;
-  /** The keys stored, in code point order. */
+  /**
+   * The keys stored, in code point order.
+   * @capability None.
+   * @throws disabled (rejects) The plugin is stopping.
+   * @throws unsupported (rejects) A player before 0.5.5.
+   * @example Clear everything the plugin stored for this run
+   * The plugin starts its session state over. `keys` lists the plugin's own
+   * keys in code point order; each `delete` is a request of its own.
+   * ```ts
+   * const session = plugin.storage.session;
+   * for (const key of await session.keys()) await session.delete(key);
+   * ```
+   */
   keys(): Promise<string[]>;
 }
 ```
@@ -9119,15 +11138,61 @@ await plugin.storage.session.set("queue", pending);
 `plugin.system`: files and links, executed by the player. No capability.
 Other systems than macOS and Windows: `unsupported`.
 
+The player opens files, folders and links with the system's own
+applications for the plugin, so the plugin never runs `open`,
+`explorer` or a shell itself.
+
+- @capability None.
+
 ```ts
 interface System {
   /**
    * Select files or folders in the file manager (macOS: one Finder window for all, so several files of one folder are all highlighted; Windows: one Explorer window per folder, selecting its first path). Paths that do not exist are skipped; `missing` when none exists; at most 256.
+   * @capability None.
+   * @throws missing (rejects) None of the paths exists.
+   * @throws invalid (rejects) No paths, or more than 256.
+   * @throws failed (rejects) The system refused.
+   * @throws timeout (rejects) macOS did not answer within 10 s.
+   * @throws unsupported (rejects) A system other than macOS and Windows.
+   * @example Show the exported files in the file manager
+   * After an export, the file manager opens with the new files selected.
+   * Paths that no longer exist are skipped; the call rejects with `missing`
+   * only when none of them exists.
+   * ```ts
+   * await plugin.system.reveal(exported); // macOS: one Finder window for all
+   * ```
    */
   reveal(paths: string | string[]): Promise<void>;
-  /** Open the file or folder with its default application. `missing` if absent. */
+  /**
+   * Open the file or folder with its default application. `missing` if absent.
+   * @capability None.
+   * @throws missing (rejects) The path does not exist.
+   * @throws invalid (rejects) An empty path.
+   * @throws failed (rejects) The system refused.
+   * @throws timeout (rejects) macOS did not answer within 10 s.
+   * @throws unsupported (rejects) A system other than macOS and Windows.
+   * @example Open the plugin's data folder
+   * A "Show data folder" command opens the plugin's data directory in the
+   * file manager, which is the default application for a folder.
+   * ```ts
+   * await plugin.system.openPath(plugin.dataDirectory);
+   * ```
+   */
   openPath(path: string): Promise<void>;
-  /** Open an http(s) address in the default browser. `invalid` for another protocol or a malformed address; `timeout` after 10 s, `failed` otherwise. */
+  /**
+   * Open an http(s) address in the default browser. `invalid` for another protocol or a malformed address; `timeout` after 10 s, `failed` otherwise.
+   * @capability None.
+   * @throws invalid (rejects) Not an `http:` or `https:` address.
+   * @throws timeout (rejects) macOS did not hand it to the browser within 10 s.
+   * @throws failed (rejects) The system refused.
+   * @throws unsupported (rejects) A system other than macOS and Windows.
+   * @example Open the plugin's help page
+   * A Help command opens the plugin's documentation in the default browser.
+   * Only `http:` and `https:` addresses are opened.
+   * ```ts
+   * await plugin.system.openUrl("https://example.com/plugin/help");
+   * ```
+   */
   openUrl(url: string): Promise<void>;
 }
 ```
@@ -9153,20 +11218,74 @@ try {
 Per-plugin secrets (API keys, passwords) in the system's secret store:
 the login keychain on macOS, the Credential Manager on Windows. Needs
 `secrets`. `unsupported` on systems without a store, `unavailable` when
-the store refuses access: keep a fallback (or ask again).
+the store cannot be reached (no keychain, a read-only store, no logged-in
+session on Windows): keep a fallback (or ask again).
 
 The user denying access and other system errors reject `failed`. Never
 write secrets to settings files.
 
+Values are stored by the player in the system's secret store under this
+plugin's id: other plugins cannot read them. Names are 1–64 of
+`a-z 0-9 . _ -`, values 1–1024 bytes of text, at most 256 names per
+plugin (`SECRET_LIMITS`).
+
+- @capability secrets
+
 ```ts
 interface Secrets {
-  /** The stored value, `null` when there is none. */
+  /**
+   * The stored value, `null` when there is none.
+   * @capability secrets
+   * @throws unsupported (rejects) The system has no secret store.
+   * @throws unavailable (rejects) The store cannot be reached (no keychain, a read-only store, no logged-in session on Windows).
+   * @throws failed (rejects) The user denied access, or another system error.
+   * @throws capability (rejects) The manifest does not declare `secrets`.
+   * @throws invalid (rejects) A bad name.
+   * @example Read a stored token
+   * The plugin uses the token the user saved earlier, or asks for one when
+   * there is none. `get` resolves with the stored text or `null`.
+   * ```ts
+   * const token = await plugin.secrets.get("api-token");
+   * if (token === null) await plugin.osd.show("Sign in first");
+   * ```
+   */
   get(name: string): Promise<string | null>;
   /**
    * Store or replace (`name`: 1–64 of `a-z 0-9 . _ -`; value 1–1024 bytes). At most 256 different names per plugin: a new name beyond that rejects `limit`. Uninstalling with `removeData` deletes them.
+   * @capability secrets
+   * @throws invalid (rejects) A bad name, or a value that is empty, has NUL or is over 1024 bytes.
+   * @throws limit (rejects) A new name beyond 256.
+   * @throws unsupported (rejects) The system has no secret store.
+   * @throws unavailable (rejects) The store cannot be reached (no keychain, a read-only store, no logged-in session on Windows).
+   * @throws failed (rejects) The user denied access, or another system error.
+   * @throws capability (rejects) The manifest does not declare `secrets`.
+   * @example Save the token the user entered
+   * The token the user typed is kept in the system's secret store for later
+   * runs. `set` stores or replaces it; the store can refuse, in which case
+   * the plugin keeps the token for this run only.
+   * ```ts
+   * await plugin.secrets.set("api-token", token).catch((error: PluginError) => {
+   *   // No store, or access denied: the token is not kept for next time.
+   *   void plugin.osd.show("The token could not be saved ({})", [error.code]);
+   * });
+   * ```
    */
   set(name: string, value: string): Promise<void>;
-  /** Remove; removing a missing secret is fine. */
+  /**
+   * Remove; removing a missing secret is fine.
+   * @capability secrets
+   * @throws invalid (rejects) A bad name.
+   * @throws unsupported (rejects) The system has no secret store.
+   * @throws unavailable (rejects) The store cannot be reached (no keychain, a read-only store, no logged-in session on Windows).
+   * @throws failed (rejects) The user denied access, or another system error.
+   * @throws capability (rejects) The manifest does not declare `secrets`.
+   * @example Sign out by removing the token
+   * Signing out removes the stored token, so the next start asks again.
+   * Removing a name that is not stored is fine.
+   * ```ts
+   * await plugin.secrets.delete("api-token");
+   * ```
+   */
   delete(name: string): Promise<void>;
 }
 ```
@@ -9591,6 +11710,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). */
@@ -9605,10 +11731,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;
 }
@@ -9651,6 +11799,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. */
@@ -9683,6 +11838,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>;
 }
@@ -9708,6 +11872,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. */
@@ -9726,17 +11897,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). */
@@ -9758,6 +11957,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.
@@ -9812,6 +12023,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. */
@@ -9894,6 +12114,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;
   /**
@@ -9901,6 +12130,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
@@ -9915,6 +12145,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;
   /**
@@ -10071,6 +12314,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
@@ -10104,6 +12348,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
@@ -10129,6 +12374,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
@@ -10159,7 +12406,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: {
@@ -10191,6 +12451,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
@@ -10228,13 +12489,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
@@ -10251,10 +12525,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. */
@@ -10266,6 +12561,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;
   /**
@@ -10281,10 +12587,22 @@ class TestHost implements Transport {
   };
   /**
    * 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
@@ -10405,10 +12723,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
@@ -10526,6 +12855,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;
@@ -10581,7 +12913,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>`);
@@ -10608,6 +12941,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
@@ -10624,17 +12958,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
@@ -10651,6 +13011,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
@@ -10677,12 +13038,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
@@ -10701,6 +13073,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
@@ -10713,8 +13086,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`
@@ -10805,6 +13181,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
@@ -10822,13 +13199,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`.
@@ -10848,6 +13259,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);
@@ -10862,6 +13274,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;
@@ -10883,6 +13296,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
@@ -10903,6 +13317,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.
@@ -10928,7 +13344,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;
 }
 ```
@@ -10978,9 +13409,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?: {
@@ -11604,7 +14040,8 @@ The plugin keeps a token the user pasted, or tells them it is empty or
 too long. Values are 1–1024 bytes counted in UTF-8, so the check uses
 `Buffer.byteLength`; `secrets.set` would refuse other values with
 `invalid`. The store itself can still refuse (`unsupported` without a
-system store, `unavailable` or `failed` when it denies access): only
+system store, `unavailable` when it cannot be reached, `failed` when the
+user denies access): only
 those codes get the "could not be saved" message, anything else (a
 missing `secrets` capability) is a bug and is thrown on.
 ```ts
@@ -11688,7 +14125,7 @@ list.on("scrolled", (row: number) => {
 
 ### IMAGE_LIMITS
 
-The player's runtime image limits (`host/src/ui_image.rs`): a file's
+The player's runtime image limits (`src/host/src/ui/ui_image.rs`): a file's
 bytes and sides, the decoded pixels each plugin caches, and (SDK 1.5.19,
 player 0.5.1) the decoded pixels the nested images of one view may show.
 
@@ -11724,11 +14161,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).
    */