@vestra-player/sdk 1.5.14 → 1.5.15

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.5.15
+
+**How many frames really reach the screen, and how the video is decoded** (player 0.5.1); every player error code documented; the fullscreen bottom bar's new behaviour. Additive; `apiVersion` stays `vestra/1`, and plugins need no change.
+
+- **`PlaybackStats.presentedFps`**: new video frames the player window showed per second over the last second, measured by the player (draws of the main window that put a new picture on screen). `framesShown` counts the frames the video renderer produced, so it cannot show frames lost afterwards, for example a window that draws only every other frame: then `presentedFps` is about half of `video.fps`. `null` when the player cannot measure it (no window, the first second) and with players before 0.5.1.
+- **`PlaybackStats.video.decoding`**: `"hardware"` or `"software"`, from mpv's `hwdec-current` (the method stays in `video.hwdec`, e.g. `"d3d11va-copy"`); `null` before a decoder runs. With players that do not send it, the SDK derives it from `hwdec`.
+- `framesShown` and `framesDropped` say what they count (TSDoc only).
+- **`TestHost`**: `host.stats` takes both fields; `presentedFps` is `null` by default, and `video.decoding` follows `video.hwdec` when a test leaves it out.
+- **`PluginError`**: the table lists the player's remaining codes with their meaning: `activation`, `command`, `input-overflow`, `internal`, `javascript`, `slint`, `owner`, `pending`, `producer`, `resolution`, `revisionConflict`, `source-geometry`, `source-geometry-unsupported`, `source-unavailable` and `unknown-expired`. `pending`, `unknown-expired` and `revisionConflict` are mostly handled inside the SDK, but can reach a plugin.
+- **`SubtitleStyle.offsetMs`**: the range is −600000…600000 ms (±10 minutes), positive shows subtitles later, and outside it the player fails with `invalid`.
+- **The fullscreen bottom bar** (player 0.5.1): it shows only while the pointer is in the bar's own band at the bottom of the screen, at once on entering and hidden 500 ms after leaving; keys and pointer motion elsewhere no longer reveal it, and `Panel.setInteraction` locks keep it. `SlotState.reason` `"idle"`, `Panel.setInteraction` and `Panels.mount` (`"bottom"`) said "hides after 3 seconds without activity".
+- `llms.txt` names the declaration files by path again (`node_modules/@vestra-player/sdk/dist/plugin/types.d.ts` for the API, `dist/plugin/testing.d.ts` for TestHost) instead of `dist/plugin/*.d.ts`.
+
 ## 1.5.14
 
 **The documentation site in seven groups, with generated reference tables.** A documentation release; `apiVersion` stays `vestra/1`, and plugins need no change. Everything a plugin author needs is now on the [documentation site](https://vestrasys.github.io/vestra-player-sdk/) once, in English.

package/dist/plugin/player.js

@@ -81,6 +81,12 @@ function view(raw) {
     raws.set(state, raw);
     return state;
 }
+/** `stats().video.decoding` from `hwdec` for players that do not send it. */
+function decoding(hwdec) {
+    if (hwdec === null || hwdec === undefined || hwdec === "")
+        return null;
+    return hwdec === "no" ? "software" : "hardware";
+}
 export const rawOf = (state) => raws.get(state);
 export const sameStamp = (a, b) => a.generation === b.generation && a.intentVersion === b.intentVersion;
 function sourceFailure(error) {
@@ -474,6 +480,7 @@ export function player(scope) {
                 session: raw.session,
                 framesShown: raw.framesShown,
                 framesDropped: raw.framesDropped,
+                presentedFps: n(raw.presentedFps),
                 video: raw.video && {
                     codec: raw.video.codec,
                     width: raw.video.width,
@@ -487,6 +494,7 @@ export function player(scope) {
                     displayFps: n(raw.video.displayFps),
                     bitrate: n(raw.video.bitrate),
                     hwdec: n(raw.video.hwdec),
+                    decoding: raw.video.decoding ?? decoding(raw.video.hwdec),
                     transfer: n(raw.video.transfer),
                 },
                 audio: raw.audio && {

package/dist/plugin/testing.js

@@ -479,6 +479,7 @@ export class TestHost {
         session: 0,
         framesShown: 0,
         framesDropped: 0,
+        presentedFps: null,
         video: null,
         audio: null,
         avSyncMs: null,

package/dist/plugin/types.d.ts

@@ -81,6 +81,19 @@ export interface Disposable {
  * | `host` | Any other failure inside the player; `message` is the player's reason. |
  * | `disabled` | The plugin is being stopped; pending requests fail with it. |
  * | `unknown`, `rejected`, `expired` | After a transport problem the SDK could not confirm the outcome (does not happen in normal operation). |
+ * | `activation` | The plugin opened a tool window while its activation was still pending and the player could not track it. |
+ * | `command` | The player could not run or update a command it no longer knows for this plugin (removed meanwhile, or another plugin's). |
+ * | `input-overflow` | `openStream` input: the player's queue of physical key transitions was full; the input was revoked and its keys released. |
+ * | `internal` | An internal step of the player failed (keeping an operation's result, a subtitle or media job); `message` has the reason. |
+ * | `javascript`, `slint` | {@link Packages.validate}: the package's entry module does not pass `node --check` / one of its Slint files does not compile; `message` has the diagnostics. |
+ * | `owner` | A resolver answered a request that belongs to another plugin's resolver. |
+ * | `pending` | An operation with the same token is still running in the player. The SDK waits and asks again, so it rarely reaches a plugin. |
+ * | `producer` | `openStream`: the player refused or lost the generated stream; `message` has the reason. |
+ * | `resolution` | A file or web resolver's result could not be opened; `message` has the reason. |
+ * | `revisionConflict` | {@link Packages}: the installed revision changed since it was read (another install, rollback or uninstall ran). Read again and retry; the SDK passes the revision it read, so this reaches plugins that act on old data. |
+ * | `source-geometry`, `source-geometry-unsupported` | The source's picture size or rotation could not be applied: invalid decoder dimensions / a rotation that is not a multiple of 90°. |
+ * | `source-unavailable` | The source is not ready (still loading, or its time or native binding is not available yet). |
+ * | `unknown-expired` | The player no longer knows the operation or snapshot (it expired or was released). The SDK maps it to `unknownExpired` results where it can; do not resubmit the operation blindly. |
  *
  * Errors thrown by handlers the SDK invokes go to {@link Scope.onError}. A
  * rejected promise you forgot to `await` is only logged; it never crashes
@@ -1345,8 +1358,10 @@ export interface SlotState {
      * - `fullscreen`: the sidebar's fullscreen overlay is collapsed and pops
      *   out when the pointer reaches the right edge; treat it as "on" for a
      *   toggle button;
-     * - `idle`: the bottom bar in fullscreen, hidden after 3 seconds without
-     *   activity.
+     * - `idle`: the bottom bar in fullscreen while the pointer is outside the
+     *   bar's own band at the bottom of the screen (player 0.5.1: keys and
+     *   pointer motion elsewhere do not bring it back; before 0.5.1 it hid after
+     *   3 seconds without activity).
      */
     reason: "userHidden" | "space" | "fullscreen" | "idle" | null;
     /** The sidebar floats in its own window; always `false` for the bottom bar. */
@@ -1783,8 +1798,11 @@ export interface Panel extends View, Disposable {
      * Keep the panel on screen while the user works in it.
      *
      * @remarks
-     * The bottom bar hides after 3 seconds without activity in fullscreen, and
-     * the fullscreen sidebar overlay collapses when the pointer leaves it. Set a
+     * In fullscreen the bottom bar shows only while the pointer is in the bar's
+     * own band at the bottom of the screen: at once when the pointer enters it,
+     * hidden 500 ms after it leaves (player 0.5.1; keys and pointer motion
+     * elsewhere do not reveal it), and the fullscreen sidebar overlay collapses
+     * when the pointer leaves it. A lock keeps the bar shown. Set a
      * lock while a text field has focus, a drag is in progress or a popup is
      * open, and clear it afterwards. Locks are merged with the earlier ones;
      * the last value of each wins. The player already locks a panel while the
@@ -2696,7 +2714,9 @@ export interface Panels {
      * - `"bottom"`: under the video, as wide as the video column, as tall as the
      *   component's preferred height. It may draw above its slot into the video
      *   area (negative `y`); the player does not clip it. In fullscreen it
-     *   floats over the video and hides after 3 seconds without activity.
+     *   floats over the video and shows only while the pointer is in its band
+     *   at the bottom of the screen (hidden 500 ms after the pointer leaves;
+     *   {@link Panel.setInteraction} locks keep it).
      * - `"sidebar"`: right of the video, the window's full height, as wide as the
      *   user drags it (at least 317). The user can detach it into a floating
      *   window titled `title`. Several plugins may mount here (player 0.4.x
@@ -3491,10 +3511,27 @@ export interface PlaybackStats {
     backend: string;
     /** The playback session number. */
     session: number;
-    /** Frames the host has shown. */
+    /**
+     * Frames the video renderer produced. Not all of them reach the screen: a
+     * busy window shows only the newest one, so compare
+     * {@link PlaybackStats.presentedFps | presentedFps}.
+     */
     framesShown: number;
-    /** Frames dropped, `null` when unknown. */
+    /** Frames dropped by the backend (mpv), `null` when unknown. */
     framesDropped: number | null;
+    /**
+     * New video frames the player window showed per second over the last
+     * second, measured by the player itself: draws of the main window that put
+     * a new picture on screen. Lower than `video.fps` when frames are lost
+     * after decoding and rendering (the window could not keep up with the
+     * source, or the display refreshes slower); `0` while paused. `null` when
+     * the player cannot measure it (no window, the first second, players
+     * before 0.5.1).
+     *
+     * @player 0.5.1
+     * @since 1.5.15
+     */
+    presentedFps: number | null;
     /** Every field is the backend's own value, `null` when it has none. */
     video: {
         /** Codec name. */
@@ -3519,8 +3556,15 @@ export interface PlaybackStats {
         displayFps: number | null;
         /** Bits per second, updated per keyframe. */
         bitrate: number | null;
-        /** Hardware decoder in use, e.g. "videotoolbox"; "no" = software decoding. */
+        /** Hardware decoder in use, e.g. "videotoolbox", "d3d11va-copy"; "no" = software decoding. */
         hwdec: string | null;
+        /**
+         * How the video is decoded, from `hwdec`: `"hardware"` (the method is in
+         * `hwdec`) or `"software"`; `null` before a decoder runs.
+         *
+         * @since 1.5.15 (with older players the SDK derives it from `hwdec`)
+         */
+        decoding: "hardware" | "software" | null;
         /** Transfer characteristic as mpv names it, e.g. "bt.1886", "pq", "hlg". */
         transfer: string | null;
     } | null;

package/dist/subtitles.d.ts

@@ -45,7 +45,11 @@ export type SubtitleStyle = {
     outline: number;
     /** Bottom margin 2–15 % of the video height. */
     marginPercent: number;
-    /** Timing offset −600000–600000 ms. */
+    /**
+     * Timing offset in milliseconds, −600000…600000 (±10 minutes); positive
+     * shows the subtitles later. Outside the range the player refuses the
+     * style with `invalid`.
+     */
     offsetMs: number;
     /** Bold text; default false. */
     bold?: boolean;

package/dist/wire.d.ts

@@ -222,6 +222,8 @@ export interface PlaybackStats {
     session: number;
     framesShown: number;
     framesDropped: number | null;
+    /** Player 0.5.1 and newer; the SDK fills in `null`. */
+    presentedFps?: number | null;
     video: {
         codec: string | null;
         width: number | null;
@@ -235,6 +237,7 @@ export interface PlaybackStats {
         displayFps?: number | null;
         bitrate?: number | null;
         hwdec?: string | null;
+        decoding?: "hardware" | "software" | null;
         transfer?: string | null;
     } | null;
     audio: {

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.14: full reference
+# @vestra-player/sdk 1.5.15: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -488,6 +488,7 @@ Reading it needs `playback.read`; following it needs `events` too:
 - The SDK reads the state once before `activate` and, with `events`, keeps `player.state` current and calls onChange listeners after every change. The state **never goes backwards**: a late event that is older than what the plugin already has is dropped.
 - Without `events`, `player.state` stays as it was first read until you call refresh().
 - Some facts are read on demand instead of pushed, because they are large or rarely needed: chapters(), stats() (codecs, frame counts, decoder, bitrates), audioDevices().
+  - In `stats()`, the frame counts come from two places. `framesShown` and `framesDropped` are the video renderer's (mpv's) counts. `presentedFps` is what the player window really showed: new frames per second over the last second. When it stays well below `video.fps` while playing, frames are lost after rendering (the window cannot keep up, or the display refreshes slower). `video.decoding` says whether the video is decoded in `"hardware"` (the method in `video.hwdec`) or `"software"`.
 
 Because the state is a snapshot, a plugin can keep one and use it later as the condition for a control.
 
@@ -2080,6 +2081,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.4.1 | PluginError, FileResolverOptions, PackageCandidate.install, PluginWarning.code, Packages.validate |
 | 0.4.2 | Resolvers.fileTypes, Resolvers.onFileTypesChange |
 | 0.4.3 | CommandOptions.path, PropValue, View.set, Appearance.setLanguage, TemplateArgs, Text, ConfirmOptions.args, OsdPanel.set, OsdPanelOptions.maxColumns, Osd.show |
+| 0.5.1 | SlotState.reason, Panel.setInteraction, PlaybackStats.presentedFps |
 
 The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
 
@@ -3059,6 +3061,19 @@ change).
 | `host` | Any other failure inside the player; `message` is the player's reason. |
 | `disabled` | The plugin is being stopped; pending requests fail with it. |
 | `unknown`, `rejected`, `expired` | After a transport problem the SDK could not confirm the outcome (does not happen in normal operation). |
+| `activation` | The plugin opened a tool window while its activation was still pending and the player could not track it. |
+| `command` | The player could not run or update a command it no longer knows for this plugin (removed meanwhile, or another plugin's). |
+| `input-overflow` | `openStream` input: the player's queue of physical key transitions was full; the input was revoked and its keys released. |
+| `internal` | An internal step of the player failed (keeping an operation's result, a subtitle or media job); `message` has the reason. |
+| `javascript`, `slint` | Packages.validate: the package's entry module does not pass `node --check` / one of its Slint files does not compile; `message` has the diagnostics. |
+| `owner` | A resolver answered a request that belongs to another plugin's resolver. |
+| `pending` | An operation with the same token is still running in the player. The SDK waits and asks again, so it rarely reaches a plugin. |
+| `producer` | `openStream`: the player refused or lost the generated stream; `message` has the reason. |
+| `resolution` | A file or web resolver's result could not be opened; `message` has the reason. |
+| `revisionConflict` | Packages: the installed revision changed since it was read (another install, rollback or uninstall ran). Read again and retry; the SDK passes the revision it read, so this reaches plugins that act on old data. |
+| `source-geometry`, `source-geometry-unsupported` | The source's picture size or rotation could not be applied: invalid decoder dimensions / a rotation that is not a multiple of 90°. |
+| `source-unavailable` | The source is not ready (still loading, or its time or native binding is not available yet). |
+| `unknown-expired` | The player no longer knows the operation or snapshot (it expired or was released). The SDK maps it to `unknownExpired` results where it can; do not resubmit the operation blindly. |
 
 Errors thrown by handlers the SDK invokes go to Scope.onError. A
 rejected promise you forgot to `await` is only logged; it never crashes
@@ -3662,8 +3677,10 @@ interface SlotState {
    * - `fullscreen`: the sidebar's fullscreen overlay is collapsed and pops
    *   out when the pointer reaches the right edge; treat it as "on" for a
    *   toggle button;
-   * - `idle`: the bottom bar in fullscreen, hidden after 3 seconds without
-   *   activity.
+   * - `idle`: the bottom bar in fullscreen while the pointer is outside the
+   *   bar's own band at the bottom of the screen (player 0.5.1: keys and
+   *   pointer motion elsewhere do not bring it back; before 0.5.1 it hid after
+   *   3 seconds without activity).
    */
   reason: "userHidden" | "space" | "fullscreen" | "idle" | null;
   /** The sidebar floats in its own window; always `false` for the bottom bar. */
@@ -4931,10 +4948,15 @@ interface PlaybackStats {
   backend: string;
   /** The playback session number. */
   session: number;
-  /** Frames the host has shown. */
+  /** Frames the video renderer produced. Not all of them reach the screen: a busy window shows only the newest one, so compare presentedFps. */
   framesShown: number;
-  /** Frames dropped, `null` when unknown. */
+  /** Frames dropped by the backend (mpv), `null` when unknown. */
   framesDropped: number | null;
+  /**
+   * New video frames the player window showed per second over the last second, measured by the player itself: draws of the main window that put a new picture on screen. Lower than `video.fps` when frames are lost after decoding and rendering (the window could not keep up with the source, or the display refreshes slower); `0` while paused. `null` when the player cannot measure it (no window, the first second, players before 0.5.1).
+   * @player 0.5.1
+   */
+  presentedFps: number | null;
   /** Every field is the backend's own value, `null` when it has none. */
   video: {
     /** Codec name. */
@@ -4959,8 +4981,10 @@ interface PlaybackStats {
     displayFps: number | null;
     /** Bits per second, updated per keyframe. */
     bitrate: number | null;
-    /** Hardware decoder in use, e.g. "videotoolbox"; "no" = software decoding. */
+    /** Hardware decoder in use, e.g. "videotoolbox", "d3d11va-copy"; "no" = software decoding. */
     hwdec: string | null;
+    /** How the video is decoded, from `hwdec`: `"hardware"` (the method is in `hwdec`) or `"software"`; `null` before a decoder runs. */
+    decoding: "hardware" | "software" | null;
     /** Transfer characteristic as mpv names it, e.g. "bt.1886", "pq", "hlg". */
     transfer: string | null;
   } | null;
@@ -6456,7 +6480,9 @@ type SubtitleStyle = {
   outline: number;
   /** Bottom margin 2–15 % of the video height. */
   marginPercent: number;
-  /** Timing offset −600000–600000 ms. */
+  /**
+   * Timing offset in milliseconds, −600000…600000 (±10 minutes); positive shows the subtitles later. Outside the range the player refuses the style with `invalid`.
+   */
   offsetMs: number;
   /** Bold text; default false. */
   bold?: boolean;
@@ -8011,10 +8037,15 @@ interface PlaybackStats {
   backend: string;
   /** The playback session number. */
   session: number;
-  /** Frames the host has shown. */
+  /** Frames the video renderer produced. Not all of them reach the screen: a busy window shows only the newest one, so compare presentedFps. */
   framesShown: number;
-  /** Frames dropped, `null` when unknown. */
+  /** Frames dropped by the backend (mpv), `null` when unknown. */
   framesDropped: number | null;
+  /**
+   * New video frames the player window showed per second over the last second, measured by the player itself: draws of the main window that put a new picture on screen. Lower than `video.fps` when frames are lost after decoding and rendering (the window could not keep up with the source, or the display refreshes slower); `0` while paused. `null` when the player cannot measure it (no window, the first second, players before 0.5.1).
+   * @player 0.5.1
+   */
+  presentedFps: number | null;
   /** Every field is the backend's own value, `null` when it has none. */
   video: {
     /** Codec name. */
@@ -8039,8 +8070,10 @@ interface PlaybackStats {
     displayFps: number | null;
     /** Bits per second, updated per keyframe. */
     bitrate: number | null;
-    /** Hardware decoder in use, e.g. "videotoolbox"; "no" = software decoding. */
+    /** Hardware decoder in use, e.g. "videotoolbox", "d3d11va-copy"; "no" = software decoding. */
     hwdec: string | null;
+    /** How the video is decoded, from `hwdec`: `"hardware"` (the method is in `hwdec`) or `"software"`; `null` before a decoder runs. */
+    decoding: "hardware" | "software" | null;
     /** Transfer characteristic as mpv names it, e.g. "bt.1886", "pq", "hlg". */
     transfer: string | null;
   } | null;

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.14: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
+> @vestra-player/sdk 1.5.15: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
 
 **Rules**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2025–2087.
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2026–2089.
 
 **main.ts**
 
@@ -76,9 +76,9 @@ export default async function activate(plugin: Plugin) {
 - `ui.settings`: Settings.page/show
 - `ui.theme`: Appearance.set/setLanguage
 - `secrets`: Secrets.get/set/delete
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2088–2130.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2090–2132.
 
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`; `host` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1587–1752; TestHost: L6649.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`; `host` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1588–1753; TestHost: L6675.
 
 **Command line**
 
@@ -106,40 +106,40 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player or another `apiVersion`
-- Others: PluginError, llms-full.txt L3027.
+- Others: PluginError, llms-full.txt L3029.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; the pages are on the [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–214
-- Concepts: How a plugin runs L215–364; Commands, menus and key bindings L365–462; Playback state, controls and sources L463–584; Video and audio processing L585–662; Windows, panels, settings pages, dialogs and the OSD L663–949
-- How-to: Keep a slider responsive while dragging L950–1124; Remember a window's state between runs L1125–1254; Translate a plugin L1255–1438; Migrate a plugin to English source text L1439–1586; Test a plugin L1587–1752; Publish a plugin L1753–1841
-- Guidelines: Interface guidelines L1842–1926; Menu guidelines L1927–2024
-- Reference: Manifest L2025–2087; Capabilities L2088–2130; Limits L2131–2225; Commands, menus and bindings L2226–2694; Platforms L2695–2723; Theme L2724–2928; Command line L2929–2984
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L2985–6484
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6485–7809
+- Concepts: How a plugin runs L215–364; Commands, menus and key bindings L365–462; Playback state, controls and sources L463–585; Video and audio processing L586–663; Windows, panels, settings pages, dialogs and the OSD L664–950
+- How-to: Keep a slider responsive while dragging L951–1125; Remember a window's state between runs L1126–1255; Translate a plugin L1256–1439; Migrate a plugin to English source text L1440–1587; Test a plugin L1588–1753; Publish a plugin L1754–1842
+- Guidelines: Interface guidelines L1843–1927; Menu guidelines L1928–2025
+- Reference: Manifest L2026–2089; Capabilities L2090–2132; Limits L2133–2227; Commands, menus and bindings L2228–2696; Platforms L2697–2725; Theme L2726–2930; Command line L2931–2986
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L2987–6510
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6511–7835
 
 ## API
 
 Where each module of `plugin` (`plugin.<module>`) is declared:
 
-- Plugin L3206, Scope L3075, PluginError L3027, Disposable L3000
-- Commands L3418; Windows L3623; Panels L4264; Dialogs L4550; Player L4991; video: VideoFilter L5256, VideoView L5319, RenderOptions L5361; audio: AudioFilter L5280; Subtitles L5459; media: MediaCapture L5619; Resolvers L5724; Packages L5964; Osd L5192; Host L5140; Clipboard L6081; Power L6101; Tools L6134; Storage L6177; System L6200; Secrets L6218; window: MainWindow L4387; App L4468; Bindings L6051; Ui L3510; Timeline L4344; Drops L3920; Appearance L3949; I18n L4091; Settings L4197.
+- Plugin L3221, Scope L3090, PluginError L3029, Disposable L3002
+- Commands L3433; Windows L3638; Panels L4281; Dialogs L4567; Player L5015; video: VideoFilter L5280, VideoView L5343, RenderOptions L5385; audio: AudioFilter L5304; Subtitles L5483; media: MediaCapture L5643; Resolvers L5748; Packages L5988; Osd L5216; Host L5164; Clipboard L6105; Power L6125; Tools L6158; Storage L6201; System L6224; Secrets L6242; window: MainWindow L4404; App L4485; Bindings L6075; Ui L3525; Timeline L4361; Drops L3937; Appearance L3966; I18n L4108; Settings L4214.
 
 ## Examples
 
 Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L8226–8315
-- blur: A tool window with one slider that blurs the playing video. L8316–8577
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8578–8910
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L8911–9095
-- panel-menu: A sidebar panel with its own right-click menu. L9096–9301
-- menus: Radio menu items, separator groups and a menu item whose title changes. L9302–9461
-- theme-widgets: A tool window drawn with the player's theme and widgets. L9462–9625
-- markdown: A window that shows a Markdown document. L9626–9820
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L9821–9988
+- hello: The README Quick start: one menu command and an on-screen message. L8259–8348
+- blur: A tool window with one slider that blurs the playing video. L8349–8610
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8611–8943
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L8944–9128
+- panel-menu: A sidebar panel with its own right-click menu. L9129–9334
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9335–9494
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9495–9658
+- markdown: A window that shows a Markdown document. L9659–9853
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L9854–10021
 
 ## Optional
 
-- [Changelog](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md); full doc comments in dist/plugin/*.d.ts; Slint library in slint/vestra/.
+- [Changelog](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md); full doc comments in node_modules/@vestra-player/sdk/dist/plugin/types.d.ts (the API) and dist/plugin/testing.d.ts (TestHost); Slint library in slint/vestra/.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.14",
+  "version": "1.5.15",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {