@vestra-player/sdk 1.5.30 → 1.5.33

package/dist/plugin/types.d.ts

@@ -43,11 +43,39 @@ export type { Json, AudioNode, VideoNode, SubtitleStyle, ResolvedMedia };
  *   if (state.phase === "ready") void subscription.dispose();
  * });
  * ```
+ *
+ * @remarks
+ * 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.
+ * @since 1.0.0
+ * @category Plugin
  */
 export interface Disposable {
     /**
      * 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
+     * });
+     * ```
+     *
+     * @since 1.0.0
      */
     dispose(): Promise<void>;
 }
@@ -59,7 +87,6 @@ export interface Disposable {
  * | code | meaning |
  * | --- | --- |
  * | `stale` | A condition no longer held (the source or the subtitle selection changed); nothing was done. See {@link Conditional}. |
- * | `staleDigest` | {@link 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). |
@@ -79,7 +106,7 @@ export interface Disposable {
  * | `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 {@link PropValue}, or a request is longer than the player's 1 MiB message. |
  * | `reserved` | {@link Packages.validate}, {@link 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 {@link 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. |
@@ -117,6 +144,9 @@ export interface Disposable {
  *   throw error;
  * }
  * ```
+ *
+ * @since 1.0.0
+ * @category Plugin
  */
 export type PluginError = Error & {
     /** The stable failure code (see the table above). */
@@ -159,6 +189,17 @@ export type PluginError = Error & {
  *   );
  * });
  * ```
+ *
+ * @remarks
+ * 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 {@link 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).
+ * @since 1.0.0
+ * @category Plugin
  */
 export interface Scope extends Disposable {
     /** Menu commands and their default bindings (`commands`). */
@@ -189,12 +230,23 @@ export interface Scope extends Disposable {
         /**
          * 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.
+         * 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.
+         * 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;
     };
@@ -258,6 +310,36 @@ export interface Scope extends Disposable {
     /**
      * 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();
+     *   },
+     * });
+     * ```
+     *
+     * @since 1.0.0
      */
     scope(): Scope;
     /**
@@ -266,6 +348,21 @@ export interface Scope extends Disposable {
      * @param item - Any {@link 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 }]);
+     * ```
+     *
+     * @since 1.0.0
      */
     add<T extends Disposable>(item: T): T;
     /**
@@ -283,6 +380,9 @@ export interface Scope extends Disposable {
      * const timer = setInterval(() => plugin.update(), 1000); // re-evaluate bindings
      * plugin.onDispose(() => clearInterval(timer));
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     onDispose(cleanup: () => void | Promise<void>): Disposable;
     /**
@@ -304,6 +404,9 @@ export interface Scope extends Disposable {
      *   void plugin.osd.show("Bookmarks: {}", [error.message]);
      * });
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     onError(listener: (error: PluginError) => void): Disposable;
     /**
@@ -313,6 +416,30 @@ export 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
+     * declare const window: Window;
+     * declare function downloadPart(part: number): Promise<void>;
+     * // ---cut---
+     * 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
+     *   }
+     * });
+     * ```
+     *
+     * @since 1.0.0
      */
     update(): void;
 }
@@ -351,6 +478,16 @@ export interface Scope extends Disposable {
  *   });
  * }
  * ```
+ *
+ * @remarks
+ * The root scope: disposing it is what stopping the plugin does. Besides
+ * the modules of {@link Scope}, it carries the plugin's `id` and its
+ * `dataDirectory`.
+ *
+ * @capability That of each module (see the modules).
+ * @see [How a plugin runs](../../docs/concepts/plugins.md)
+ * @since 1.0.0
+ * @category Plugin
  */
 export interface Plugin extends Scope {
     /** The manifest id, e.g. `"community.bookmark"`. */
@@ -372,7 +509,13 @@ export interface Plugin extends Scope {
      */
     readonly dataDirectory: string;
 }
-/** The state of a command's menu item, as the player shows it. */
+/**
+ * The state of a command's menu item, as the player shows it.
+ *
+ * @see {@link Command.set}, {@link CommandOptions}
+ * @since 1.0.0
+ * @category Commands
+ */
 export interface CommandState {
     /** False greys the item out; the player then never calls `run` (bound keys are swallowed). Default true. */
     enabled: boolean;
@@ -404,6 +547,9 @@ export interface CommandState {
  *   run: () => plugin.player.setLoop(null),
  * });
  * ```
+ *
+ * @since 1.0.0
+ * @category Commands
  */
 export type Bindable<T> = T | (() => T);
 /**
@@ -411,6 +557,9 @@ export type Bindable<T> = T | (() => T);
  * `@<id>` or by its English key (see {@link CommandOptions.path}): Open,
  * Playback, Subtitles, Video, Audio, Screen, Settings. The list is
  * `MENU_IDS` in `@vestra-player/sdk/testing`.
+ *
+ * @since 1.3.0
+ * @category Commands
  */
 export type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "screen" | "settings";
 /**
@@ -419,6 +568,8 @@ export type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "sc
  * `@vestra-player/sdk/testing`.
  *
  * @since 1.5.29
+ *
+ * @category Commands
  */
 export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "open" | "volume" | "mute" | "playlist" | "detach" | "attach" | "close" | "failed" | "move-top" | "move-up" | "move-down" | "move-bottom" | "search" | "chapter" | "bookmark" | "check-task" | "check-box" | "menu-check" | "submenu" | "scroll-up" | "scroll-down" | "caret-down" | "sort-asc" | "sort-desc" | "tag-remove" | "preview-play" | "add" | "remove" | "sort" | "fullscreen" | "exit-fullscreen" | "store" | "ai";
 /**
@@ -470,6 +621,8 @@ export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "op
  * @player 0.5.10; older players show the menu entry without a button
  * (declare `"minPlayerVersion": "0.5.10"` when the button matters).
  * @since 1.5.29
+ *
+ * @category Commands
  */
 export interface CommandButton {
     /**
@@ -518,6 +671,10 @@ export interface CommandButton {
  * {@link Commands.add} throws `invalid` synchronously for a bad path,
  * order, group or binding. The same path registered twice, or a path that
  * is both an item and a submenu, fails with `conflict` (through `ready`).
+ *
+ * @see {@link Commands.add}, [Commands, menus and key bindings](../../docs/concepts/commands.md)
+ * @since 1.0.0
+ * @category Commands
  */
 export interface CommandOptions {
     /** Local id, unique within the plugin (the global id is `<manifest id>/<id>`). */
@@ -644,6 +801,38 @@ export interface CommandOptions {
 /**
  * A registered command, from {@link Commands.add}. Disposing it removes it
  * from the menu and the binding table; the id can be added again right away.
+ *
+ * @remarks
+ * The handle of one menu item and its keys. Its state (`enabled`, `checked`,
+ * `busy`, `reason`) is bound: functions given to {@link Commands.add} or
+ * {@link 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 {@link 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
+ *
+ * @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
+ * declare function runExport(): Promise<void>;
+ * // ---cut---
+ * 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" });
+ * ```
+ *
+ * @see {@link Commands.add}, [Commands, menus and key bindings](../../docs/concepts/commands.md)
+ * @since 1.0.0
+ * @category Commands
  */
 export interface Command extends Disposable {
     /** The local id given in {@link CommandOptions.id}. */
@@ -672,6 +861,9 @@ export interface Command extends Disposable {
      *   },
      * });
      * ```
+     *
+     * @capability commands
+     * @since 1.0.0
      */
     set(state: Partial<{
         [K in keyof CommandState]: Bindable<CommandState[K]>;
@@ -682,10 +874,49 @@ export interface Command extends Disposable {
      * 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 {@link 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>;
 }
-/** `plugin.commands`: menu commands with default bindings. Needs `commands`. */
+/**
+ * `plugin.commands`: menu commands with default bindings. Needs `commands`.
+ *
+ * @remarks
+ * 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
+ * {@link Command.ready} reports the player's answer (during activation a
+ * refusal fails activation).
+ *
+ * @capability 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"),
+ * });
+ * ```
+ *
+ * @see {@link Command}, {@link CommandOptions}, [Commands, menus and key bindings](../../docs/concepts/commands.md)
+ * @since 1.0.0
+ * @category Commands
+ */
 export interface Commands {
     /**
      * Declare a command. It is registered and kept in sync; `dispose()` removes
@@ -715,6 +946,9 @@ export interface Commands {
      *   run: () => plugin.player.setPaused(!plugin.player.state.paused),
      * });
      * ```
+     *
+     * @capability commands
+     * @since 1.0.0
      */
     add(options: CommandOptions): Command;
 }
@@ -2325,7 +2559,12 @@ export interface Panel extends View, Disposable {
         modifiers: DropModifiers;
     }) => unknown): Disposable;
 }
-/** Keys held when the files were dropped. */
+/**
+ * Keys held when the files were dropped.
+ *
+ * @since 1.0.0
+ * @category UI
+ */
 export interface DropModifiers {
     /** Option (macOS) / Alt (Windows). */
     readonly alt: boolean;
@@ -2334,7 +2573,13 @@ export interface DropModifiers {
     /** ⌘ on macOS, Ctrl on Windows. */
     readonly cmd: boolean;
 }
-/** A provider for files dropped on the video area ({@link Drops.provide}). */
+/**
+ * A provider for files dropped on the video area ({@link Drops.provide}).
+ *
+ * @see {@link Drops.provide}
+ * @since 1.0.0
+ * @category UI
+ */
 export interface DropHandler {
     /**
      * Lower case, without the dot; `"folder"` matches directories.
@@ -2347,7 +2592,39 @@ export interface DropHandler {
         modifiers: DropModifiers;
     }): unknown;
 }
-/** `plugin.drops`: files dropped on the video area. Needs `ui.drop`. */
+/**
+ * `plugin.drops`: files dropped on the video area. Needs `ui.drop`.
+ *
+ * @remarks
+ * 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 {@link Panel.onDrop} takes drops on itself first.
+ *
+ * @capability ui.drop
+ *
+ * @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
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link Panel.onDrop}
+ * @since 1.0.0
+ * @category UI
+ */
 export interface Drops {
     /**
      * Take files dropped on the video area. The first provider registered for
@@ -2381,6 +2658,9 @@ export interface Drops {
      *   },
      * });
      * ```
+     *
+     * @capability ui.drop
+     * @since 1.0.0
      */
     provide(handler: DropHandler): Disposable;
 }
@@ -3297,9 +3577,19 @@ export interface Panels {
     /** The sidebar position, including its floating state; any plugin may read and toggle it. */
     readonly sidebar: SidebarSlot;
 }
-/** What a timeline mark stands for; readers choose colours by it. */
+/**
+ * What a timeline mark stands for; readers choose colours by it.
+ *
+ * @since 1.0.0
+ * @category Playback
+ */
 export type MarkKind = "chapter" | "bookmark" | "marker";
-/** One mark on the seek bar. */
+/**
+ * One mark on the seek bar.
+ *
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface TimelineMark {
     /** Seconds from the start. */
     readonly time: number;
@@ -3310,7 +3600,28 @@ export interface TimelineMark {
     /** The manifest id of the plugin that published it. */
     readonly plugin: string;
 }
-/** This plugin's own marks; disposing it removes them. */
+/**
+ * This plugin's own marks; disposing it removes them.
+ *
+ * @remarks
+ * This plugin's marks on the seek bar, from {@link 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
+ *
+ * @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([]);
+ * ```
+ *
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface TimelineLayer extends Disposable {
     /**
      * Replace the layer (last write wins; `[]` clears it). At most 1000 marks,
@@ -3335,6 +3646,9 @@ export interface TimelineLayer extends Disposable {
      *   { ifCurrent: seen },
      * );
      * ```
+     *
+     * @capability timeline.marks
+     * @since 1.0.0
      */
     set(marks: {
         time: number;
@@ -3347,16 +3661,79 @@ export interface TimelineLayer extends Disposable {
 /**
  * `plugin.timeline`: marks on the seek bar. Every plugin publishes one
  * layer; the player merges them. A new source clears every layer.
+ *
+ * @remarks
+ * Marks on the player's seek bar: chapters, bookmarks, loop points. Each
+ * plugin publishes one layer with {@link 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.
+ *
+ * @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]);
+ * ```
+ *
+ * @since 1.0.0
+ * @category Playback
  */
 export 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}`));
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * ]);
+     * ```
+     *
+     * @since 1.0.0
+     */
     layer(): TimelineLayer;
 }
-/** The main window as `plugin.window.state` reports it (logical points). */
+/**
+ * The main window as `plugin.window.state` reports it (logical points).
+ *
+ * @see {@link MainWindow.state}
+ * @since 1.0.0
+ * @category Plugin
+ */
 export interface WindowState {
     /** The main window is fullscreen. */
     readonly fullscreen: boolean;
@@ -3406,11 +3783,38 @@ export interface WindowState {
  *   },
  * });
  * ```
+ *
+ * @remarks
+ * `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.
+ * @since 1.0.0
+ * @category Plugin
  */
 export 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
+     * declare const bar: Panel;
+     * // ---cut---
+     * plugin.window.onChange((state) => bar.set({ large: state.fullscreen }));
+     * ```
+     *
+     * @since 1.0.0
+     */
     onChange(listener: (state: WindowState) => void): Disposable;
     /**
      * Resize the window so the video column is `width`×`height` (the bottom bar
@@ -3422,6 +3826,23 @@ export 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]);
+     * ```
+     *
+     * @since 1.0.0
      */
     setVideoArea(size: {
         width: number;
@@ -3437,12 +3858,53 @@ export interface MainWindow {
     /**
      * 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
+     *   },
+     * });
+     * ```
+     *
+     * @since 1.0.0
      */
     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");
+     * ```
+     *
+     * @since 1.0.0
      */
     setCursorAutoHide(mode: "fullscreen" | "playing"): Promise<void>;
     /**
@@ -3467,10 +3929,26 @@ export interface MainWindow {
      * if (plugin.window.state.pictureInPicture.supported)
      *   await plugin.window.setPictureInPicture(!plugin.window.state.pictureInPicture.active);
      * ```
+     *
+     * @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`.
+     * @since 1.0.0
      */
     setPictureInPicture(on: boolean): Promise<void>;
 }
-/** `plugin.app`: fixed for the life of the plugin process. */
+/**
+ * `plugin.app`: fixed for the life of the plugin process.
+ *
+ * @since 1.0.0
+ * @category Plugin
+ */
 export interface AppInfo {
     /** The player's version, e.g. `"1.0.0"`. */
     readonly version: string;
@@ -3500,15 +3978,47 @@ export interface AppInfo {
  * const system = await plugin.app.system();
  * const text = `Vestra ${plugin.app.version} on ${system.name} ${system.version ?? ""}`;
  * ```
+ *
+ * @remarks
+ * `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.
+ * @since 1.0.0
+ * @category Plugin
  */
 export 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.
+     *
+     * @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);
+     * ```
+     *
+     * @since 1.0.0
      */
     system(): Promise<SystemInfo>;
 }
-/** What {@link App.system} reports. */
+/**
+ * What {@link App.system} reports.
+ *
+ * @see {@link App.system}
+ * @since 1.0.0
+ * @category Plugin
+ */
 export interface SystemInfo {
     /** The operating system family. */
     readonly os: "macos" | "windows" | "linux" | "other";
@@ -3525,7 +4035,12 @@ export interface SystemInfo {
     /** Primary display first; empty without a user interface. */
     readonly displays: readonly DisplayInfo[];
 }
-/** One display in {@link SystemInfo.displays}. */
+/**
+ * One display in {@link SystemInfo.displays}.
+ *
+ * @since 1.0.0
+ * @category Plugin
+ */
 export interface DisplayInfo {
     /** The system's name for it, `null` when it has none. */
     readonly name: string | null;
@@ -3814,7 +4329,12 @@ export interface Dialogs {
         fileName?: TextValue;
     }): Promise<string | null>;
 }
-/** One audio track of the current media ({@link PlayerState.audioTracks}). */
+/**
+ * One audio track of the current media ({@link PlayerState.audioTracks}).
+ *
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface AudioTrack {
     /** The backend's track id; pass it to {@link Player.selectAudioTrack}. */
     id: number;
@@ -3836,6 +4356,10 @@ export interface AudioTrack {
  *
  * Without `events`, {@link Player.state} only updates at start and after
  * this plugin's own operations.
+ *
+ * @see {@link Player.state}, [Playback state, controls and sources](../../docs/concepts/playback.md)
+ * @since 1.0.0
+ * @category Playback
  */
 export interface PlayerState {
     /** Changes every time a source is opened, even the same file again. */
@@ -3913,14 +4437,24 @@ export interface PlayerState {
         active: string | null;
     };
 }
-/** An audio output device (`player.audioDevices`). */
+/**
+ * An audio output device (`player.audioDevices`).
+ *
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface AudioDevice {
     /** Stable id to pass to `setAudioDevice` (e.g. `coreaudio/<UID>`). */
     id: string;
     /** What the system calls it. */
     name: string;
 }
-/** One chapter of the current media. */
+/**
+ * One chapter of the current media.
+ *
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface Chapter {
     /** Chapter title, `null` without one. */
     title: string | null;
@@ -3955,12 +4489,41 @@ export interface Chapter {
  *   }
  * });
  * ```
+ *
+ * @see [Playback state, controls and sources](../../docs/concepts/playback.md)
+ * @since 1.0.0
+ * @category Playback
  */
 export interface Conditional {
     /** The state the call is conditional on; default: the current `player.state`. */
     ifCurrent?: PlayerState;
 }
-/** A source this plugin opened. */
+/**
+ * A source this plugin opened.
+ *
+ * @remarks
+ * A source this plugin opened with {@link 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 {@link Player.open} (`playback.control`); `ready` and
+ * `onEnd` follow the state through `events` and `playback.read`.
+ *
+ * @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
+ * ```
+ *
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface Media {
     /** Still the player's source (a restart keeps it current). */
     readonly current: boolean;
@@ -3968,13 +4531,77 @@ export interface Media {
      * 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 {@link 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]);
+     * }
+     * ```
+     *
+     * @since 1.0.0
      */
     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 {@link 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
+     * declare const media: Media;
+     * declare const next: string;
+     * // ---cut---
+     * media.onEnd((ended) =>
+     *   plugin.player.open(next, { ifCurrent: ended }).catch((error: PluginError) => {
+     *     if (error.code !== "stale") throw error; // the user opened something else
+     *   }),
+     * );
+     * ```
+     *
+     * @since 1.0.0
+     */
     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 {@link 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
+     * declare const preview: Media;
+     * // ---cut---
+     * await preview.close(); // a no-op when something else is playing now
+     * ```
+     *
+     * @since 1.0.0
+     */
     close(): Promise<void>;
 }
 /**
@@ -3997,6 +4624,18 @@ export interface Media {
  * bar.on("dragMove", (seconds: number) => void scrub?.seek(seconds));
  * bar.on("dragEnd", () => scrub?.end());
  * ```
+ *
+ * @remarks
+ * 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
+ * @see [Keep a slider responsive while dragging](../../docs/how-to/slider.md)
+ * @since 1.0.0
+ * @category Playback
  */
 export interface Scrub {
     /**
@@ -4029,13 +4668,40 @@ export interface Scrub {
      * const keyframes = true; // the plugin's own setting
      * bar.on("dragMove", (seconds: number) => void scrub?.seek(seconds, { keyframes }));
      * ```
+     *
+     * @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.
+     * @since 1.0.0
      */
     seek(seconds: number, options?: {
         keyframes?: boolean;
     }): 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
+     * declare const bar: Panel;
+     * declare const scrub: Scrub;
+     * // ---cut---
+     * bar.on("dragEnd", () => scrub.end()); // later seeks resolve false
+     * ```
+     *
+     * @since 1.0.0
+     */
     end(): void;
 }
 /**
@@ -4049,6 +4715,9 @@ export interface Scrub {
  *
  * The SDK copies the frame once before `frame()` is called again, so you
  * may reuse the same buffers for every frame.
+ *
+ * @since 1.0.0
+ * @category Playback
  */
 export interface StreamFrame {
     /** `width × height × 4` bytes of RGBA, at most 4 MiB. */
@@ -4060,7 +4729,13 @@ export interface StreamFrame {
      */
     audio: Float32Array;
 }
-/** Options of {@link Player.openStream}. */
+/**
+ * Options of {@link Player.openStream}.
+ *
+ * @see {@link Player.openStream}
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface StreamOptions {
     /** Frame width in pixels. */
     width: number;
@@ -4075,12 +4750,48 @@ export interface StreamOptions {
  * `openStream` start-up timeouts: code `timeout` with the step that ran out
  * of time, the first buffers (`prefill`) or the host's activation.
  * Both limits are 10 seconds.
+ *
+ * @since 1.0.0
+ * @category Playback
  */
 export type StreamStartError = PluginError & {
     /** The start-up step that timed out. */
     stage: "prefill" | "activation";
 };
-/** A generated source, from {@link Player.openStream}. Disposing it stops it. */
+/**
+ * A generated source, from {@link Player.openStream}. Disposing it stops it.
+ *
+ * @remarks
+ * A source whose frames this plugin generates, from
+ * {@link 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
+ *
+ * @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
+ * declare const stream: Stream;
+ * // ---cut---
+ * // Enabled while the stream produces frames.
+ * plugin.commands.add({
+ *   id: "stop-generator",
+ *   path: ["@playback", "Stop generator"],
+ *   enabled: () => stream.running,
+ *   run: () => stream.stop(),
+ * });
+ * ```
+ *
+ * @see {@link Player.openStream}
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface Stream extends Disposable {
     /** The stream is producing frames. */
     readonly running: boolean;
@@ -4096,6 +4807,23 @@ export 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
+     * declare const stream: Stream;
+     * // ---cut---
+     * stream.onStop((error) => {
+     *   if (error) void plugin.osd.show("Generator stopped: {}", [error.message]);
+     * });
+     * ```
+     *
+     * @since 1.0.0
      */
     onStop(listener: (error: PluginError | null) => void): Disposable;
     /**
@@ -4103,10 +4831,34 @@ export interface Stream extends Disposable {
      * 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
+     * declare const stream: Stream;
+     * declare const window: Window;
+     * // ---cut---
+     * window.onClose(() => stream.stop());
+     * ```
+     *
+     * @since 1.0.0
      */
     stop(): Promise<void>;
 }
-/** The plugin that owns "next / previous" (a playlist). */
+/**
+ * The plugin that owns "next / previous" (a playlist).
+ *
+ * @see {@link Player.provideSequence}
+ * @since 1.0.0
+ * @category Playback
+ */
 export interface SequenceProvider {
     /** Go to the next item (called in the provider's scope). */
     next(): unknown;
@@ -4120,6 +4872,10 @@ export interface SequenceProvider {
 /**
  * What {@link Player.stats} reports. Every field is the backend's own value
  * (libmpv properties), `null` when it has none; nothing is converted.
+ *
+ * @see {@link Player.stats}
+ * @since 1.0.0
+ * @category Playback
  */
 export interface PlaybackStats {
     /**
@@ -4234,15 +4990,90 @@ export interface PlaybackStats {
  *   void plugin.osd.show("Cannot play: {}", [(error as Error).message]);
  * }
  * ```
+ *
+ * @remarks
+ * `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
+ * {@link 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
+ * {@link Player.openStream}.
+ *
+ * @see [Playback state, controls and sources](../../docs/concepts/playback.md), [Control playback](../../docs/how-to/control-playback.md)
+ * @since 1.0.0
+ * @category Playback
  */
 export 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) ?? ""]);
+     * });
+     * ```
+     *
+     * @since 1.0.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)]);
+     * ```
+     *
+     * @since 1.0.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
+     * declare function lookUpTitle(path: string): Promise<string>;
+     * // ---cut---
+     * 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
+     * ```
+     *
+     * @since 1.0.0
+     */
     isCurrent(state: PlayerState): boolean;
     /**
      * Open a path or URL, replacing the current source (unless `ifCurrent` no
@@ -4253,6 +5084,37 @@ export interface Player {
      * {@link 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 {@link 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
+     * ```
+     *
+     * @since 1.0.0
      */
     open(source: string, options?: {
         paused?: boolean;
@@ -4290,32 +5152,219 @@ export interface Player {
      * // `error` is null when the stream stopped normally.
      * stream.onStop((error) => error && plugin.osd.show(error.message));
      * ```
+     *
+     * @capability producer.av and playback.control
+     * @throws `timeout` (rejects) A {@link 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`).
+     * @since 1.0.0
      */
     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
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * ```
+     *
+     * @since 1.0.0
+     */
     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]);
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     */
     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 {@link Media} handle stays current.
+     * ```ts
+     * if (plugin.player.state.phase === "ended") await plugin.player.restart();
+     * ```
+     *
+     * @since 1.0.0
+     */
     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);
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * declare const bar: Panel;
+     * // ---cut---
+     * let scrub: Scrub | null = null;
+     * bar.on("dragStart", () => (scrub = plugin.player.scrub()));
+     * bar.on("dragEnd", () => scrub?.end());
+     * ```
+     *
+     * @see [Keep a slider responsive while dragging](../../docs/how-to/slider.md)
+     * @since 1.0.0
+     */
     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.
+     *
+     * @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 });
+     * ```
+     *
+     * @since 1.0.0
      */
     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 ({@link PluginInfo.warnings});
+     * a refusal after activation goes to the scope's `onError`. Dispose to
+     * stop.
      *
      * @example Drive the player's Next and Previous from a playlist
      * The player's Next and Previous items and keys play the plugin's list.
@@ -4339,15 +5388,82 @@ export interface Player {
      *   canPrevious: () => index > 0,
      * });
      * ```
+     *
+     * @capability playback.control
+     * @since 1.0.0
      */
     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");
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     */
     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(),
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     previous(): Promise<void>;
     /**
      * 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]);
+     * ```
+     *
+     * @since 1.0.0
      */
     stats(): Promise<PlaybackStats>;
     /**
@@ -4355,11 +5471,56 @@ export interface Player {
      * 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
+     * declare const dubPath: string;
+     * // ---cut---
+     * const track = await plugin.player.addAudioTrack(dubPath); // selected too
+     * await plugin.osd.show("Audio: {}", [track.title ?? dubPath]);
+     * ```
+     *
+     * @since 1.0.0
      */
     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);
+     * ```
+     *
+     * @since 1.0.0
+     */
     selectAudioTrack(id: number, options?: Conditional): Promise<PlayerState>;
     /**
      * One frame or to the next / previous keyframe (pauses for frames). Rejects
@@ -4369,6 +5530,29 @@ export 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) ?? "?"]);
+     * ```
+     *
+     * @since 1.0.0
      */
     step(unit: "frame" | "keyframe", direction: "backward" | "forward", options?: Conditional): Promise<void>;
     /**
@@ -4391,6 +5575,23 @@ export 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 });
+     * ```
+     *
+     * @since 1.0.0
      */
     setStepSeek(options: {
         seconds: number;
@@ -4400,6 +5601,23 @@ export interface Player {
      * 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));
+     * ```
+     *
+     * @since 1.0.0
      */
     chapters(): Promise<{
         /** The source the chapters belong to (compare with `state.sourceId`). */
@@ -4413,13 +5631,59 @@ export interface Player {
      * 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
+     * ```
+     *
+     * @since 1.0.0
      */
     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),
+     *   });
+     * ```
+     *
+     * @since 1.0.0
+     */
     audioDevices(): Promise<AudioDevice[]>;
     /**
      * Play on this device while it is present, else on the system default
@@ -4429,6 +5693,23 @@ export 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
+     * ```
+     *
+     * @since 1.0.0
      */
     setAudioDevice(id: string | null): Promise<void>;
 }
@@ -4453,9 +5734,45 @@ export interface Player {
  * (`plugin.window.onChange`), which also changes when the user toggles it.
  * Players before 0.5.2 reject it with `invalid`: set
  * `"minPlayerVersion": "0.5.2"` when you use it.
+ *
+ * @see {@link Host.run}
+ * @since 1.0.0
+ * @category Commands
  */
 export type HostAction = "play-pause" | "stop" | "previous" | "next" | "frame-back" | "frame-forward" | "seek-backward" | "seek-forward" | "rate-down" | "rate-up" | "rate-normal" | "volume-up" | "volume-down" | "mute" | "fullscreen";
-/** `plugin.host`: the player's own core actions. */
+/**
+ * `plugin.host`: the player's own core actions.
+ *
+ * @remarks
+ * 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 {@link Player} calls.
+ *
+ * @capability commands
+ *
+ * @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
+ * declare const bar: Panel;
+ * // ---cut---
+ * 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"));
+ * ```
+ *
+ * @see {@link HostAction}, {@link Player}
+ * @since 1.0.0
+ * @category Commands
+ */
 export interface Host {
     /**
      * Run a core action exactly like its menu item or key: same checks, same
@@ -4482,6 +5799,14 @@ export interface Host {
      *   }
      * });
      * ```
+     *
+     * @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`.
+     *
+     * @since 1.0.0
      */
     run(action: HostAction): Promise<void>;
     /**
@@ -4511,6 +5836,12 @@ export interface Host {
      * // ---cut---
      * bar.on("forward30", () => plugin.host.run("seek-forward", { seconds: 30 }));
      * ```
+     *
+     * @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`.
      */
     run(action: "seek-backward" | "seek-forward", options: {
         seconds: number;
@@ -4717,6 +6048,9 @@ export interface Osd {
  * The state of a filter, display layer or render options handle.
  * After `failed` nothing retries automatically until the next `set()`,
  * `retry()` or a new source.
+ *
+ * @since 1.0.0
+ * @category Processing
  */
 export type FilterStatus = 
 /** No ready media; the value is kept and applied when media is ready. */
@@ -4792,6 +6126,18 @@ interface Filter<T> extends Disposable {
  * picture.onStatus((s) => s.state === "failed" && plugin.osd.show(s.error.message));
  * picture.set([{ kind: "eq", brightness: 0.1, contrast: 1.1, saturation: 1, gamma: 1 }]);
  * ```
+ *
+ * @remarks
+ * 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
+ * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @since 1.0.0
+ * @category Processing
  */
 export type VideoFilter = Filter<VideoNode[]>;
 /**
@@ -4811,6 +6157,16 @@ export type VideoFilter = Filter<VideoNode[]>;
  * const audio = plugin.audio.filter("sound");
  * audio.set({ nodes: [{ kind: "volume", gainDb: -6 }], delayMs: 120 }); // 10 ms steps
  * ```
+ *
+ * @remarks
+ * The same members and rules as {@link 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
+ * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @since 1.0.0
+ * @category Processing
  */
 export type AudioFilter = Filter<{
     /** The audio chain; `[]` for none. */
@@ -4821,6 +6177,9 @@ export type AudioFilter = Filter<{
 /**
  * How the video sits in the video area; not part of snapshots or exports.
  * Defaults: `{ aspect: null, fit: "keep", zoom: 1, panX: 0, panY: 0 }`.
+ *
+ * @since 1.0.0
+ * @category Processing
  */
 export interface ViewSettings {
     /** Display aspect override 0.25–4; `null` = as the source. */
@@ -4848,24 +6207,73 @@ export interface ViewSettings {
  * 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" });
  * view.set({ zoom: 1.5, panX: 0.1 }); // merged with the previous write
  * ```
+ *
+ * @remarks
+ * 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
+ * {@link VideoFilter})
+ * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @since 1.0.0
+ * @category Processing
  */
 export 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" });
+     * ```
+     *
+     * @since 1.0.0
+     */
     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");
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     onStatus(listener: (status: FilterStatus) => void): Disposable;
 }
 /**
  * GPU renderer options; not part of snapshots or exports.
  * Defaults: `{ toneMapping: "auto", targetPeak: 203, peakDetect: true, shaders: [], interpolation: false }`.
+ *
+ * @since 1.0.0
+ * @category Processing
  */
 export interface RenderSettings {
     /** HDR → SDR: "auto" maps HDR sources only; "off" clips without a curve. */
@@ -4904,19 +6312,69 @@ export interface RenderSettings {
  * });
  * render.set({ toneMapping: "bt.2390", targetPeak: 250 }); // nits
  * ```
+ *
+ * @remarks
+ * 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 {@link VideoView}. `set` never throws; the
+ * result shows in `status`.
+ *
+ * @capability processing.video, playback.read and events (like
+ * {@link VideoFilter})
+ * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @since 1.0.0
+ * @category Processing
  */
 export 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 });
+     * ```
+     *
+     * @since 1.0.0
+     */
     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]);
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     onStatus(listener: (status: FilterStatus) => void): Disposable;
 }
-/** A subtitle track of the current source. */
+/**
+ * A subtitle track of the current source.
+ *
+ * @since 1.0.0
+ * @category Subtitles
+ */
 export interface SubtitleTrack {
     /** Stable while the track exists; compare tracks by id. */
     id: string;
@@ -4944,7 +6402,13 @@ export interface SubtitleTrack {
      */
     streamIndex: number | null;
 }
-/** The subtitle state of the current source. */
+/**
+ * The subtitle state of the current source.
+ *
+ * @see {@link Subtitles.state}
+ * @since 1.0.0
+ * @category Subtitles
+ */
 export interface SubtitlesState {
     /** The source it belongs to ({@link PlayerState.sourceId}). */
     readonly sourceId: number;
@@ -4975,7 +6439,12 @@ export interface SubtitlesState {
     /** The last error, `null` without one. */
     readonly error: string | null;
 }
-/** Subtitle calls act on the selection you see; pass `ifCurrent` to pin an older one. */
+/**
+ * Subtitle calls act on the selection you see; pass `ifCurrent` to pin an older one.
+ *
+ * @since 1.0.0
+ * @category Subtitles
+ */
 export interface SubtitleConditional {
     /** The subtitle state the call is conditional on; `stale` otherwise. */
     ifCurrent?: SubtitlesState;
@@ -5009,18 +6478,104 @@ export interface SubtitleConditional {
  *   offsetMs: 0,
  * });
  * ```
+ *
+ * @remarks
+ * 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.
+ *
+ * @see [Load subtitles from a plugin](../../docs/how-to/subtitles.md)
+ * @since 1.0.0
+ * @category Subtitles
  */
 export 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"]);
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     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]);
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     *   });
+     * ```
+     *
+     * @since 1.0.0
      */
     select(track: SubtitleTrack | null, options?: SubtitleConditional & {
         role?: "primary" | "secondary";
@@ -5037,6 +6592,36 @@ export 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
+     * declare const url: string;
+     * // ---cut---
+     * 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]);
+     * ```
+     *
+     * @since 1.0.0
      */
     load(bytes: Uint8Array, options?: SubtitleConditional & {
         format?: "srt" | "ass";
@@ -5044,19 +6629,69 @@ export 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
+     * declare const loaded: SubtitleTrack;
+     * // ---cut---
+     * await plugin.subtitles.remove(loaded);
+     * ```
+     *
+     * @since 1.0.0
+     */
     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);
+     * ```
+     *
+     * @since 1.0.0
      */
     setStyle(style: SubtitleStyle | null, options?: SubtitleConditional): Promise<SubtitlesState>;
 }
 /**
  * Options of {@link MediaCapture.capture}. Conditional on `player.state`
  * like other controls.
+ *
+ * @since 1.0.0
+ * @category Media
  */
 export interface CaptureOptions extends Conditional {
     /** Source time; defaults to the current position at the moment of capture. */
@@ -5068,7 +6703,36 @@ export interface CaptureOptions extends Conditional {
     /** Audio to freeze with the snapshot: the selected track, none, or a track id. */
     audio?: "selected" | "none" | number;
 }
-/** A frozen, immutable input for exports. Dispose to release it. */
+/**
+ * A frozen, immutable input for exports. Dispose to release it.
+ *
+ * @remarks
+ * A frozen input, from {@link 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
+ *
+ * @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();
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Media
+ */
 export interface Snapshot extends Disposable {
     /** Without or with effects. */
     readonly kind: "raw" | "processed";
@@ -5092,6 +6756,32 @@ export interface Snapshot extends Disposable {
     /**
      * 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
+     * declare const snapshot: Snapshot;
+     * // ---cut---
+     * 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]);
+     * ```
+     *
+     * @since 1.0.0
      */
     export(options: ExportOptions): Promise<ExportJob>;
 }
@@ -5103,6 +6793,9 @@ export interface Snapshot extends Disposable {
  * choose the format. `sampleTime` picks the frame (default: the snapshot
  * time); `end` is the clip's end in source seconds. On Windows the export
  * worker needs FFmpeg 6.1 or newer.
+ *
+ * @since 1.0.0
+ * @category Media
  */
 export type ExportOptions = {
     /** A lossless frame. */
@@ -5133,19 +6826,111 @@ export type ExportOptions = {
  * `completed`, `failed` or `cancelled`; once terminal, `outcome` is
  * `{ destination }`, `{ error: { code, message } }` or `{ cancelled: true }`.
  * `facts` describes what the worker produced (versions, range, streams).
+ *
+ * @since 1.0.0
+ * @category Media
  */
 export type JobState = Omit<MediaJob, "jobId">;
-/** An export, from {@link Snapshot.export}. Disposing an unfinished job cancels it. */
+/**
+ * An export, from {@link Snapshot.export}. Disposing an unfinished job cancels it.
+ *
+ * @remarks
+ * One export, from {@link 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
+ *
+ * @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
+ * declare const job: ExportJob;
+ * // ---cut---
+ * 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
+ * ```
+ *
+ * @since 1.0.0
+ * @category Media
+ */
 export 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
+     * declare const job: ExportJob;
+     * // ---cut---
+     * job.onChange((state) => console.log("export", state.status));
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * declare const job: ExportJob;
+     * // ---cut---
+     * const answer = await job.cancel();
+     * if (answer === "tooLate") await plugin.osd.show("Too late: the file is being written");
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * declare const job: ExportJob;
+     * // ---cut---
+     * const state = await job.refresh();
+     * console.log(state.status);
+     * ```
+     *
+     * @since 1.0.0
+     */
     refresh(): Promise<JobState>;
 }
 /**
@@ -5173,21 +6958,73 @@ export interface ExportJob extends Disposable {
  *   await snapshot.dispose();
  * }
  * ```
+ *
+ * @remarks
+ * Exports run in the player's offline worker from a frozen
+ * {@link 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`)
+ * @since 1.0.0
+ * @category Media
  */
 export 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.
+     * `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
+     * }
+     * ```
+     *
+     * @since 1.0.0
      */
     capture(options?: CaptureOptions): Promise<Snapshot>;
 }
 /**
  * Declaration of {@link Resolvers.add}: a web resolver
  * ({@link WebResolverOptions}) or a file resolver ({@link FileResolverOptions}).
+ *
+ * @since 1.0.0
+ * @category Sources
  */
 export type ResolverOptions = WebResolverOptions | FileResolverOptions;
-/** A resolver for web pages: `https://host/…` to playable stream URLs. */
+/**
+ * A resolver for web pages: `https://host/…` to playable stream URLs.
+ *
+ * @since 1.0.0
+ * @category Sources
+ */
 export interface WebResolverOptions {
     /** Local id, unique within the plugin. */
     id: string;
@@ -5252,6 +7089,9 @@ export interface WebResolverOptions {
  *   },
  * });
  * ```
+ *
+ * @since 1.5.3
+ * @category Sources
  */
 export interface FileResolverOptions {
     /** Local id, unique within the plugin. */
@@ -5276,6 +7116,9 @@ export interface FileResolverOptions {
  * failures "无法启动播放". An error thrown by `frame()` keeps its message.
  * To give your own text for a file you can tell is unusable (a bad header),
  * check it in `resolve` and throw there.
+ *
+ * @since 1.5.3
+ * @category Sources
  */
 export interface ResolvedStream {
     /** Always `"stream"`. */
@@ -5294,14 +7137,52 @@ export interface ResolvedStream {
      */
     started?(stream: Stream): void;
 }
-/** A registered resolver. Disposing it unregisters it and aborts resolutions in flight. */
-export interface Resolver extends Disposable {
-    /**
-     * Resolves when the player registered it; rejects otherwise: `conflict`
+/**
+ * A registered resolver. Disposing it unregisters it and aborts resolutions in flight.
+ *
+ * @remarks
+ * A registered resolver, from {@link 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
+ *
+ * @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");
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ * @category Sources
+ */
+export 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>;
 }
@@ -5328,6 +7209,20 @@ export interface Resolver extends Disposable {
  *   },
  * });
  * ```
+ *
+ * @remarks
+ * A resolver turns something the player cannot play by itself into
+ * something it can: a web page address into stream URLs
+ * ({@link WebResolverOptions}), or a local file of a format the plugin
+ * understands into a stream the plugin generates
+ * ({@link 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`)
+ * @see [Playback state, controls and sources](../../docs/concepts/playback.md)
+ * @since 1.0.0
+ * @category Sources
  */
 export interface Resolvers {
     /**
@@ -5336,6 +7231,29 @@ export interface Resolvers {
      * 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 } };
+     *   },
+     * });
+     * ```
+     *
+     * @since 1.0.0
      */
     add(options: ResolverOptions): Resolver;
     /**
@@ -5391,6 +7309,9 @@ export interface Resolvers {
  * The manifest of a package, as validated. The display fields and
  * `minPlayerVersion` are optional (player 0.2.0); see the API reference for
  * their rules.
+ *
+ * @since 1.0.0
+ * @category Packages
  */
 export interface PackageManifest {
     /** Plugin id. */
@@ -5431,6 +7352,9 @@ export interface PackageManifest {
  * upgrade the plugin and keep its data; links and local files count as one
  * source. `bundled` marks the player's built-in plugins (set by the player
  * only).
+ *
+ * @since 1.1.0
+ * @category Packages
  */
 export type PackageSource = {
     /** A repository. */
@@ -5452,7 +7376,12 @@ export type PackageSource = {
     /** Shipped with the player (built-in). */
     kind: "bundled";
 };
-/** Options of {@link PackageCandidate.install}. */
+/**
+ * Options of {@link PackageCandidate.install}.
+ *
+ * @since 1.1.0
+ * @category Packages
+ */
 export interface InstallOptions {
     /**
      * Where the package comes from (default `{ kind: "file" }`). Repository
@@ -5467,7 +7396,34 @@ export interface InstallOptions {
      */
     replace?: boolean;
 }
-/** A validated package directory, from {@link Packages.validate}. */
+/**
+ * A validated package directory, from {@link Packages.validate}.
+ *
+ * @remarks
+ * A package the player has checked, from {@link Packages.validate} or
+ * {@link 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 {@link PackageChange}; the player keeps only the 32
+ * most recent candidates.
+ *
+ * @capability plugins.manage
+ *
+ * @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
+ * declare const directory: string;
+ * // ---cut---
+ * const candidate = await plugin.packages.validate(directory);
+ * const { id, version, capabilities } = candidate.manifest;
+ * await plugin.osd.show("{} {}: {}", [id, version, capabilities.join(", ")]);
+ * ```
+ *
+ * @since 1.0.0
+ * @category Packages
+ */
 export interface PackageCandidate {
     /** The package directory. */
     readonly directory: string;
@@ -5484,28 +7440,138 @@ export interface PackageCandidate {
      * 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
+     * declare const candidate: PackageCandidate;
+     * // ---cut---
+     * const change = await candidate.install({ replace: true });
+     * await change.done; // "committed" once the new plugin runs
+     * ```
+     *
+     * @since 1.0.0
      */
     install(options?: InstallOptions): Promise<PackageChange>;
 }
-/** The progress of an install or uninstall. */
+/**
+ * The progress of an install or uninstall.
+ *
+ * @since 1.0.0
+ * @category Packages
+ */
 export type PackageChangeStatus = "preparing" | "activating" | "restoring" | "committed" | "cancelled" | "failed" | "failedDegraded" | "tooLate";
 /**
  * An install or uninstall in progress. The SDK never submits a
  * change twice: after a lost reply it only queries the same request.
+ *
+ * @remarks
+ * 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
+ *
+ * @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
+ * declare const change: PackageChange;
+ * // ---cut---
+ * 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]);
+ * ```
+ *
+ * @since 1.0.0
+ * @category Packages
  */
 export 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
+     * declare const change: PackageChange;
+     * declare const progress: Window;
+     * // ---cut---
+     * change.onChange((status) => {
+     *   if (["committed", "cancelled", "failed", "failedDegraded", "tooLate"].includes(status))
+     *     void progress.close();
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * declare const change: PackageChange;
+     * // ---cut---
+     * await change.cancel();
+     * console.log(await change.done); // "cancelled"; "committed" when it was too late
+     * ```
+     *
+     * @since 1.0.0
+     */
     cancel(): Promise<void>;
 }
-/** One plugin as the player knows it (`packages.list`). */
+/**
+ * One plugin as the player knows it (`packages.list`).
+ *
+ * @since 1.0.0
+ * @category Packages
+ */
 export interface PluginInfo {
     /** Manifest id. */
     id: string;
@@ -5564,6 +7630,8 @@ export interface PluginInfo {
  * `description` and `tags` as the player shows them.
  *
  * @since 1.5.9
+ *
+ * @category Packages
  */
 export interface PluginDisplay {
     /** `name`, translated; `null` when the manifest has none. */
@@ -5579,6 +7647,8 @@ export interface PluginDisplay {
  * One refusal in {@link PluginInfo.warnings}.
  *
  * @since 1.5.2
+ *
+ * @category Packages
  */
 export interface PluginWarning {
     /**
@@ -5615,6 +7685,17 @@ export interface PluginWarning {
  * // `message` says why a change did not commit.
  * if ((await change.done) !== "committed") throw new Error(change.message ?? "install failed");
  * ```
+ *
+ * @remarks
+ * 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.
+ * @since 1.0.0
+ * @category Packages
  */
 export interface Packages {
     /**
@@ -5625,6 +7706,37 @@ export 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
+     * declare const directory: string;
+     * // ---cut---
+     * 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]);
+     * }
+     * ```
+     *
+     * @since 1.0.0
      */
     validate(directory: string): Promise<PackageCandidate>;
     /**
@@ -5632,19 +7744,97 @@ export interface Packages {
      * same checks as {@link Packages.validate} after unpacking. Check the
      * file's sha256 yourself before calling when you know it. A reserved id
      * fails with `reserved`, as in {@link 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
+     * declare const file: string;
+     * // ---cut---
+     * const candidate = await plugin.packages.validateArchive(file); // a .vxp path
+     * const change = await candidate.install();
+     * await plugin.osd.show("Install: {}", [await change.done]);
+     * ```
+     *
+     * @since 1.1.0
      */
     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));
+     * ```
+     *
+     * @since 1.0.0
+     */
     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"));
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * `busy` while it is being installed or reloaded. `unsupported` to disable a built-in
      * ({@link 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);
+     * ```
+     *
+     * @since 1.0.0
      */
     setEnabled(id: string, enabled: boolean): Promise<void>;
     /**
@@ -5665,6 +7855,23 @@ export interface Packages {
      * @player 0.5.1; older players reject it as an unknown request
      * (`unsupported`).
      * @since 1.5.19
+     *
+     * @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>;
     /**
@@ -5673,19 +7880,51 @@ export interface Packages {
      * 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;
+     * ```
+     *
+     * @since 1.0.0
      */
     uninstall(id: string, options?: {
         removeData?: boolean;
     }): Promise<PackageChange>;
 }
-/** A command: manifest id (`"host"` for the player's own) and command id. */
+/**
+ * A command: manifest id (`"host"` for the player's own) and command id.
+ *
+ * @since 1.0.0
+ * @category Commands
+ */
 export interface BindingRef {
     /** Manifest id, or `"host"`. */
     plugin: string;
     /** Command id within that plugin. */
     command: string;
 }
-/** One command's bindings, from {@link Bindings.list}. */
+/**
+ * One command's bindings, from {@link Bindings.list}.
+ *
+ * @since 1.0.0
+ * @category Commands
+ */
 export interface BindingInfo extends BindingRef {
     /** Menu title. */
     title: string;
@@ -5735,9 +7974,40 @@ export interface BindingInfo extends BindingRef {
  * // later
  * await plugin.bindings.reset({ plugin: "host", command: "mute" });
  * ```
+ *
+ * @remarks
+ * The player's binding table: every command's default keys (from
+ * {@link 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
+ * @see [Commands, menus and key bindings](../../docs/concepts/commands.md)
+ * @since 1.0.0
+ * @category Commands
  */
 export 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
+     * ```
+     *
+     * @since 1.0.0
+     */
     list(): Promise<{
         /** Every declared command (running plugins and the player). */
         commands: BindingInfo[];
@@ -5754,11 +8024,65 @@ export interface Bindings {
      * `invalid` for a bad binding, `missing` for an unknown command that has
      * no override either.
      * At most 16 inputs, syntax as {@link 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"]);
+     * ```
+     *
+     * @since 1.0.0
      */
     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
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * declare function render(commands: BindingInfo[]): void;
+     * // ---cut---
+     * plugin.bindings.onChange(async () => {
+     *   const { commands } = await plugin.bindings.list(); // read the new table
+     *   render(commands);
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     onChange(listener: () => void): Disposable;
 }
 /**
@@ -5782,16 +8106,109 @@ export interface Bindings {
  *   void plugin.osd.show("Could not copy: {}", [(error as PluginError).code]);
  * }
  * ```
+ *
+ * @remarks
+ * 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
+ * @since 1.0.0
+ * @category Services
  */
 export 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());
+     * ```
+     *
+     * @since 1.0.0
+     */
     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);
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * declare const pngPath: string;
+     * // ---cut---
+     * await plugin.clipboard.writeImage(pngPath); // absolute path, at most 16 MB
+     * await plugin.osd.show("Snapshot copied");
+     * ```
+     *
+     * @since 1.0.0
+     */
     writeImage(path: string): Promise<void>;
 }
-/** Keeping the computer awake (`playback.control`). */
+/**
+ * Keeping the computer awake (`playback.control`).
+ *
+ * @remarks
+ * 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
+ *
+ * @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
+ * ```
+ *
+ * @since 1.0.0
+ * @category Services
+ */
 export interface Power {
     /**
      * `"playing"`: while a source is ready and not paused, keep the display
@@ -5802,10 +8219,32 @@ export 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");
+     * ```
+     *
+     * @since 1.0.0
      */
     preventSleep(mode: "off" | "playing"): Promise<void>;
 }
-/** The output of {@link Tools.run}. */
+/**
+ * The output of {@link Tools.run}.
+ *
+ * @see {@link Tools.run}
+ * @since 1.0.0
+ * @category Services
+ */
 export interface ToolResult {
     /** Standard output (at most `maxOutput` bytes). */
     stdout: Uint8Array;
@@ -5835,11 +8274,23 @@ export interface ToolResult {
  *   void info.format; // container, duration, bit rate…
  * }
  * ```
+ *
+ * @remarks
+ * 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.
+ * @since 1.0.0
+ * @category Services
  */
 export 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.
@@ -5847,28 +8298,171 @@ export 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
+     * declare const input: string;
+     * declare const output: string;
+     * // ---cut---
+     * await plugin.tools.run(
+     *   "ffmpeg",
+     *   ["-y", "-i", input, "-t", "10", "-c", "copy", output],
+     *   { timeoutMs: 60_000 }, // give up after a minute
+     * );
+     * ```
+     *
+     * @since 1.0.0
      */
     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() {},
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     available(tool: "ffmpeg" | "ffprobe"): Promise<boolean>;
 }
-/** A JSON file `dataDirectory/<name>.json`, loaded once and saved debounced. */
+/**
+ * A JSON file `dataDirectory/<name>.json`, loaded once and saved debounced.
+ *
+ * @remarks
+ * One JSON file, `<dataDirectory>/<name>.json`, made by
+ * {@link 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.
+ *
+ * @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
+ * ```
+ *
+ * @since 1.0.0
+ * @category Services
+ */
 export 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.
+     *
+     * @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
+     * declare const window: Window;
+     * // ---cut---
+     * const store = plugin.storage.json("prefs", { defaults: { volume: 100 } });
+     * window.on("volumeChanged", (volume: number) => store.save({ ...store.value, volume }));
+     * ```
+     *
+     * @since 1.0.0
      */
     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
+     * import { copyFile } from "node:fs/promises";
+     * import { join } from "node:path";
+     * declare const exportPath: string;
+     * // ---cut---
+     * 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);
+     * ```
+     *
+     * @since 1.0.0
+     */
     flush(): Promise<void>;
 }
-/** `plugin.storage`: JSON settings files. No capability. */
+/**
+ * `plugin.storage`: JSON settings files. No capability.
+ *
+ * @remarks
+ * Two kinds of storage, both private to the plugin and needing no
+ * capability. {@link 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. {@link 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
+ * {@link Secrets}, never in either.
+ *
+ * @capability None.
+ *
+ * @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;
+ * ```
+ *
+ * @see [Store a plugin's data](../../docs/how-to/store-data.md), [Remember a window's state between runs](../../docs/how-to/window-state.md)
+ * @since 1.0.0
+ * @category Services
+ */
 export interface Storage {
     /**
      * Open `<name>.json` (`name`: 1–64 of `a-z 0-9 -`). A file that cannot be
@@ -5897,6 +8491,11 @@ export interface Storage {
      * // Only `save` writes: changing `store.value` in place is not saved.
      * store.save({ ...store.value, recent: [path, ...store.value.recent].slice(0, 10) });
      * ```
+     *
+     * @capability None.
+     * @throws `invalid` (throws) A bad `name`, or a `debounceMs` that is not a
+     *   non-negative number.
+     * @since 1.0.0
      */
     json<T>(name: string, options: {
         defaults: T;
@@ -5970,19 +8569,97 @@ export interface Storage {
  * ```
  *
  * @since 1.5.25
+ *
+ * @remarks
+ * 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.
+ * @category Services
  */
 export 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]);
+     * ```
+     *
+     * @since 1.5.25
+     */
     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" });
+     * ```
+     *
+     * @since 1.5.25
      */
     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");
+     * ```
+     *
+     * @since 1.5.25
+     */
     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);
+     * ```
+     *
+     * @since 1.5.25
+     */
     keys(): Promise<string[]>;
 }
 /**
@@ -6005,6 +8682,15 @@ export interface SessionStorage {
  *   await plugin.osd.show(`Saved to ${exportedFile}`); // no file manager to open
  * }
  * ```
+ *
+ * @remarks
+ * 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.
+ * @since 1.0.0
+ * @category Services
  */
 export interface System {
     /**
@@ -6012,13 +8698,66 @@ export interface System {
      * 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
+     * declare const exported: string[];
+     * // ---cut---
+     * await plugin.system.reveal(exported); // macOS: one Finder window for all
+     * ```
+     *
+     * @since 1.0.0
      */
     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);
+     * ```
+     *
+     * @since 1.0.0
+     */
     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.
+     *
+     * @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");
+     * ```
+     *
+     * @since 1.0.0
      */
     openUrl(url: string): Promise<void>;
 }
@@ -6026,7 +8765,8 @@ export interface System {
  * 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.
@@ -6052,16 +8792,96 @@ export interface System {
  *     await plugin.secrets.set("api-token", token).catch(() => {}); // best effort
  * }
  * ```
+ *
+ * @remarks
+ * 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
+ * @since 1.0.0
+ * @category Services
  */
 export 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");
+     * ```
+     *
+     * @since 1.0.0
+     */
     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
+     * declare const token: string;
+     * // ---cut---
+     * 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]);
+     * });
+     * ```
+     *
+     * @since 1.0.0
      */
     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");
+     * ```
+     *
+     * @since 1.0.0
+     */
     delete(name: string): Promise<void>;
 }