@vestra-player/sdk 1.5.31 → 1.5.34

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"`. */
@@ -2422,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;
@@ -2431,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.
@@ -2444,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
@@ -2478,6 +2658,9 @@ export interface Drops {
      *   },
      * });
      * ```
+     *
+     * @capability ui.drop
+     * @since 1.0.0
      */
     provide(handler: DropHandler): Disposable;
 }
@@ -3394,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;
@@ -3407,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,
@@ -3432,6 +3646,9 @@ export interface TimelineLayer extends Disposable {
      *   { ifCurrent: seen },
      * );
      * ```
+     *
+     * @capability timeline.marks
+     * @since 1.0.0
      */
     set(marks: {
         time: number;
@@ -3444,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;
@@ -3503,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
@@ -3519,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;
@@ -3534,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>;
     /**
@@ -3564,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;
@@ -3597,15 +3978,48 @@ 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.
+     * The operating system, the displays and the renderer, read when called
+     * (displays come and go; the renderer can fall back from GPU to software
+     * once). No capability. CPU and memory: Node's `os` module.
+     *
+     * @capability None.
+     * @throws `busy` (rejects) The player could not start the request (no
+     *   thread available).
+     *
+     * @example Choose a size for the primary display
+     * The plugin sizes its picture for the primary display. `system()` asks
+     * the player; `displays` lists the displays present now, the primary one
+     * first (empty without a user interface).
+     * ```ts
+     * const { displays } = await plugin.app.system();
+     * const primary = displays[0];
+     * if (primary) console.log(primary.width, primary.height);
+     * ```
+     *
+     * @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";
@@ -3621,8 +4035,53 @@ export interface SystemInfo {
     readonly arch: string;
     /** Primary display first; empty without a user interface. */
     readonly displays: readonly DisplayInfo[];
+    /**
+     * Which renderer draws the video now: `"gpu"` (the GPU renderer, so
+     * {@link RenderOptions | render options} apply) or `"software"` (they
+     * fail with `unsupported`). Read at each call. It changes at most once
+     * while the player runs, from `"gpu"` to `"software"` when a window
+     * cannot show GPU frames; the owner of the render options hears that
+     * switch through {@link RenderOptions.onStatus}.
+     *
+     * Absent (`undefined`) on players before 0.5.12, which do not report it:
+     * the renderer is then unknown, not software.
+     *
+     * Today the player renders on the GPU on macOS and in software on
+     * Windows, Linux and without a user interface (see
+     * [Platforms](../../docs/reference/platforms.md)); test this field
+     * rather than {@link SystemInfo.os}.
+     *
+     * @example Offer the HDR menu only where render options work
+     * The plugin adds its HDR command only when the player renders on the
+     * GPU, instead of creating the render options just to find out from a
+     * failed status. `system()` asks the player, which reports the renderer
+     * drawing at that moment; no capability is needed to ask. A player before
+     * 0.5.12 leaves the field out, so the test is for `"gpu"` exactly (an
+     * older player gets no HDR command).
+     * ```ts
+     * const { rendering } = await plugin.app.system();
+     * if (rendering === "gpu") {
+     *   const render = plugin.video.render(); // one handle, kept
+     *   plugin.commands.add({
+     *     id: "hdr",
+     *     path: ["@video", "HDR Tone Mapping"],
+     *     run: () => render.set({ toneMapping: "bt.2390", targetPeak: 250 }),
+     *   });
+     * }
+     * ```
+     *
+     * @player 0.5.12; older players leave it out (declare
+     * `"minPlayerVersion": "0.5.12"` when the plugin relies on it).
+     * @since 1.5.34
+     */
+    readonly rendering?: "gpu" | "software";
 }
-/** 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;
@@ -5630,6 +6089,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. */
@@ -5705,6 +6167,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[]>;
 /**
@@ -5724,6 +6198,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. */
@@ -5734,6 +6218,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. */
@@ -5761,24 +6248,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. */
@@ -5799,8 +6335,10 @@ export interface RenderSettings {
  *
  * Platforms: only macOS renders on the GPU. Under software rendering
  * (Windows, Linux, headless, fallback) every `set` fails with
- * `unsupported`. macOS OpenGL 4.1 has no compute shaders, so `peakDetect`
- * is accepted but has no effect; output is always SDR.
+ * `unsupported`; {@link SystemInfo.rendering} tells which renderer draws
+ * without creating the handle. macOS OpenGL 4.1 has no
+ * compute shaders, so `peakDetect` is accepted but has no effect; output
+ * is always SDR.
  *
  * @example Tone-map HDR video and hide the menu where it cannot work
  * On a GPU-rendering player HDR video is tone-mapped with BT.2390 for a
@@ -5817,19 +6355,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. */
-    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). */
-    onStatus(listener: (status: FilterStatus) => void): Disposable;
-}
-/** A subtitle track of the current source. */
+     * 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).
+     *
+     * @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.
+ *
+ * @since 1.0.0
+ * @category Subtitles
+ */
 export interface SubtitleTrack {
     /** Stable while the track exists; compare tracks by id. */
     id: string;
@@ -5857,7 +6445,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;
@@ -5888,7 +6482,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;
@@ -5922,18 +6521,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";
@@ -5949,7 +6634,43 @@ 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.
+     * (VTT, SAMI) to SRT first. Per source, a plugin has at most 4 loaded
+     * tracks at once and loads at most 16 files (removed ones count), and
+     * every plugin together at most 16 tracks; see `SUBTITLE_LIMITS` in
+     * `@vestra-player/sdk/testing`.
+     *
+     * @capability subtitles.control and subtitles.read
+     * @throws `invalid` (rejects) A bad `format` or `title`, or a file over the
+     *   limits.
+     * @throws `stale` (rejects) With `ifCurrent`: the source changed since
+     *   that state.
+     * @throws `unavailable` (rejects) Nothing loaded, or the source is still
+     *   loading.
+     * @throws `aborted` (rejects) `signal` aborted before the commit (an
+     *   `AbortError`); the upload is discarded.
+     * @throws `busy` (rejects) Too many subtitle operations at once, or a
+     *   limit of `SUBTITLE_LIMITS` is reached (4 tracks of this plugin, 16
+     *   loads of this plugin or 16 tracks in the source, or another of its
+     *   limits); nothing is loaded.
+     * @throws `capability` (rejects) The manifest does not declare
+     *   `subtitles.control` and `subtitles.read`.
+     *
+     * @example Load a downloaded SRT and select it
+     * A subtitle file the plugin downloaded becomes a track of the current file
+     * and is selected. The plugin passes the file's bytes; the player parses
+     * them, adds an `external` track for this source only and resolves with
+     * it once the upload is committed.
+     * ```ts
+     * 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";
@@ -5957,19 +6678,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. */
@@ -5981,7 +6752,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";
@@ -6005,6 +6805,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>;
 }
@@ -6016,6 +6842,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. */
@@ -6046,19 +6875,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>;
 }
 /**
@@ -6086,21 +7007,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;
@@ -6165,6 +7138,9 @@ export interface WebResolverOptions {
  *   },
  * });
  * ```
+ *
+ * @since 1.5.3
+ * @category Sources
  */
 export interface FileResolverOptions {
     /** Local id, unique within the plugin. */
@@ -6189,6 +7165,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"`. */
@@ -6207,7 +7186,38 @@ export interface ResolvedStream {
      */
     started?(stream: Stream): void;
 }
-/** A registered resolver. Disposing it unregisters it and aborts resolutions in flight. */
+/**
+ * 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`
@@ -6215,6 +7225,13 @@ export interface Resolver extends Disposable {
      * 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>;
 }
@@ -6241,6 +7258,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 {
     /**
@@ -6249,6 +7280,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;
     /**
@@ -6304,6 +7358,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. */
@@ -6344,6 +7401,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. */
@@ -6365,7 +7425,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
@@ -6380,7 +7445,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;
@@ -6397,28 +7489,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;
@@ -6477,6 +7679,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. */
@@ -6492,6 +7696,8 @@ export interface PluginDisplay {
  * One refusal in {@link PluginInfo.warnings}.
  *
  * @since 1.5.2
+ *
+ * @category Packages
  */
 export interface PluginWarning {
     /**
@@ -6528,6 +7734,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 {
     /**
@@ -6538,6 +7755,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>;
     /**
@@ -6545,19 +7793,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>;
     /**
@@ -6578,6 +7904,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>;
     /**
@@ -6586,19 +7929,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;
@@ -6648,9 +8023,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[];
@@ -6667,11 +8073,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;
 }
 /**