@vestra-player/sdk 1.5.14 → 1.5.16

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.5.16
+
+**Package rollback is deprecated: the player keeps no previous plugin version.** `apiVersion` stays `vestra/1`; code still compiles, and plugins that do not manage other plugins need no change. 1.5.17 removes the deprecated symbols, as 1.5.8 removed `PackageCandidate.trial()` at patch level. Migration: [Migrating off package rollback](docs/how-to/rollback-migration.md).
+
+- **Deprecated: `Packages.rollback`** (removed in 1.5.17). The player no longer has `packages.rollback` and answers it with `unsupported` ("unknown package method"); the SDK still forwards the call, so the error reaches the caller. To go back to an older version of a third-party plugin, the user uninstalls it and installs that version's `.vxp`.
+- **Deprecated: `PluginInfo.previousVersion`** and the wire field `PackageInfo.previousVersion` (removed in 1.5.17): always `null`, since an upgrade replaces the package. The SDK reads a missing field as `null`.
+- **Built-in plugins** run in place from the player installation: `PluginInfo.directory` of a built-in is `<install resources>/plugins/<id>` and read-only (plugins write only under `plugin.dataDirectory`); they can be disabled and enabled, not uninstalled (`unsupported`, as before).
+- **`TestHost`** matches the player: `packages.list` and `packages.changed` report `previousVersion: null` for every plugin, an install no longer records the replaced version, and `packages.rollback` rejects with `unsupported` ("unknown package method"). The `previousVersion` field of `host.packages` entries is deprecated and ignored; it stays required (as `PluginInfo.previousVersion` does), so existing test code compiles unchanged.
+- `"Packages.rollback"` stays in `CAPABILITY_INFO["plugins.manage"].apis` until 1.5.17; the Capabilities reference notes the deprecation.
+- Docs: the new how-to *Migrating off package rollback (1.5.16)*; *Publish a plugin* no longer mentions a roll back button, installing an older version from the store or the user's rollback as a safety net; the data directory is "kept across restarts, disabling and upgrades"; `revisionConflict`, `PackageChange` and `PackageChangeStatus` speak of installs and uninstalls (the statuses are unchanged).
+
+## 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/packages.js

@@ -1,4 +1,4 @@
-/** Package validation and install/rollback (`plugins.manage`). */
+/** Package validation, install and uninstall (`plugins.manage`). */
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { failure, sleep, uncertain } from "./runtime.js";
@@ -62,7 +62,7 @@ class ChangeHandle {
         this.#accept(await this.#scope.runtime.host.packages.cancel(this.#id));
     }
 }
-/** Install and rollback reuse the request id as the operation id after a lost reply. */
+/** Install and uninstall reuse the request id as the operation id after a lost reply. */
 async function change(scope, submit, id) {
     const host = scope.runtime.host.packages;
     const installed = await host.installed(id);
@@ -126,6 +126,8 @@ export const packages = (scope) => ({
         const checked = await scope.runtime.host.packages.validateArchive(path);
         return candidate(scope, path, checked);
     },
+    // Deprecated (removed in 1.5.17): still forwarded, so the player's
+    // `unsupported` ("unknown package method") reaches the caller.
     rollback: (id) => change(scope, (requestId, revision) => scope.runtime.host.packages.rollback(id, revision, requestId), id),
     list: async () => (await scope.runtime.host.packages.list()).map(info),
     onChange(listener) {
@@ -152,7 +154,7 @@ const info = (plugin) => Object.freeze({
     error: plugin.error,
     capabilities: [...plugin.capabilities],
     directory: plugin.directory,
-    previousVersion: plugin.previousVersion,
+    previousVersion: plugin.previousVersion ?? null,
     builtin: plugin.builtin === true,
     source: plugin.source ? Object.freeze({ ...plugin.source }) : null,
     dataDirectory: plugin.dataDirectory ?? null,

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.d.ts

@@ -1311,7 +1311,9 @@ export declare class TestHost implements Transport {
     /**
      * What `packages.list` reports; `setEnabled`, `uninstall` and `install`
      * update it. `builtin`, `source` and `dataDirectory` are optional here
-     * (default `false`, `null`, `null`).
+     * (default `false`, `null`, `null`). Like the player, the host lists every
+     * plugin with `previousVersion: null` and answers `packages.rollback` with
+     * `unsupported` (since 1.5.16).
      */
     packages: {
         /** The plugin's manifest id. */
@@ -1328,7 +1330,12 @@ export declare class TestHost implements Transport {
         capabilities: string[];
         /** The package directory. */
         directory: string;
-        /** The version a rollback would restore, `null` without one. */
+        /**
+         * Ignored: `packages.list` always reports `null`. Still required in
+         * 1.5.16 so that test data shaped like a `PluginInfo` keeps compiling.
+         *
+         * @deprecated Removed in 1.5.17 with `PluginInfo.previousVersion`.
+         */
         previousVersion: string | null;
         /** Shipped with the player: `uninstall` and `install` are `unsupported`. */
         builtin?: boolean;

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,
@@ -1861,7 +1862,9 @@ export class TestHost {
     /**
      * What `packages.list` reports; `setEnabled`, `uninstall` and `install`
      * update it. `builtin`, `source` and `dataDirectory` are optional here
-     * (default `false`, `null`, `null`).
+     * (default `false`, `null`, `null`). Like the player, the host lists every
+     * plugin with `previousVersion: null` and answers `packages.rollback` with
+     * `unsupported` (since 1.5.16).
      */
     packages = [];
     /** Every `packages.setEnabled` / `uninstall` / `install`, newest last. */
@@ -1918,7 +1921,14 @@ export class TestHost {
      */
     setPackages(list) {
         this.packages = list;
-        this.emit("packages.changed", structuredClone(list));
+        this.emit("packages.changed", this.#listed());
+    }
+    /** `packages.list` as the player sends it: no previous version is kept. */
+    #listed() {
+        return this.packages.map((entry) => ({
+            ...structuredClone(entry),
+            previousVersion: null,
+        }));
     }
     #split(key) {
         const at = key.indexOf("/");
@@ -3152,7 +3162,7 @@ export class TestHost {
                 this.bindings.overlay.delete(`${p.plugin}/${p.command}`);
             this.emit("bindings.changed", null);
         },
-        "packages.list": () => structuredClone(this.packages),
+        "packages.list": () => this.#listed(),
         "packages.setEnabled": (p) => {
             const id = String(p.id);
             if (id === this.manifestId && p.enabled === false)
@@ -3204,9 +3214,7 @@ export class TestHost {
                 error: null,
                 capabilities: [...manifest.capabilities],
                 directory: `/test-host/packages/${manifest.id}`,
-                previousVersion: entry && identity(entry.source) === identity(source)
-                    ? entry.version
-                    : null,
+                previousVersion: null,
                 builtin: false,
                 source,
                 dataDirectory: entry?.dataDirectory ?? null,
@@ -3234,6 +3242,11 @@ export class TestHost {
             this.setPackages(this.packages.filter((each) => each.id !== id));
             return { operationId: String(p.requestId), status: "committed" };
         },
+        // The player no longer keeps a previous version (SDK 1.5.16): the method
+        // is gone and fails like any unknown package method.
+        "packages.rollback": () => {
+            throw new HostError("unsupported", "unknown package method");
+        },
         "ui.markdownScan": (p) => {
             const text = String(p.text);
             const images = [

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 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
@@ -323,7 +336,7 @@ export interface Plugin extends Scope {
      * A writable directory for this plugin's own files (settings, caches,
      * remembered folders), created by the player before it starts the plugin.
      * Each installation has its own directory (player 0.2.0): it is kept across
-     * restarts, disabling, upgrades and rollbacks, and a reinstall of the same
+     * restarts, disabling and upgrades, and a reinstall of the same
      * id from a different source gets a new, empty one. It is deleted only by
      * `packages.uninstall(id, { removeData: true })`. No capability.
      *
@@ -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;
@@ -4649,10 +4693,10 @@ export interface PackageCandidate {
      */
     install(options?: InstallOptions): Promise<PackageChange>;
 }
-/** The progress of an install, rollback or uninstall. */
+/** The progress of an install or uninstall. */
 export type PackageChangeStatus = "preparing" | "activating" | "restoring" | "committed" | "cancelled" | "failed" | "failedDegraded" | "tooLate";
 /**
- * An install, rollback or uninstall in progress. The SDK never submits a
+ * An install or uninstall in progress. The SDK never submits a
  * change twice: after a lost reply it only queries the same request.
  */
 export interface PackageChange {
@@ -4681,9 +4725,21 @@ export interface PluginInfo {
     error: string | null;
     /** Declared capabilities. */
     capabilities: string[];
-    /** The package directory (read its `manifest.json` for display fields). */
+    /**
+     * The package directory (read its `manifest.json` for display fields).
+     * A built-in's directory is inside the player installation
+     * (`<install resources>/plugins/<id>`) and read-only: a plugin writes only
+     * under its own {@link Plugin.dataDirectory}.
+     */
     directory: string;
-    /** The version a rollback would restore, `null` without one. */
+    /**
+     * Always `null`: the player no longer keeps a previous version, and an
+     * upgrade replaces the package.
+     *
+     * @deprecated Removed in 1.5.17. The player no longer keeps a previous
+     * version, so this is always `null`. See
+     * [Migrating off package rollback](../../docs/how-to/rollback-migration.md).
+     */
     previousVersion: string | null;
     /**
      * Shipped with the player: it can be disabled, not uninstalled or
@@ -4783,7 +4839,15 @@ export interface Packages {
      * fails with `reserved`, as in {@link Packages.validate}.
      */
     validateArchive(file: string): Promise<PackageCandidate>;
-    /** Restore a plugin's previous version (`plugins.manage`). */
+    /**
+     * Formerly restored a plugin's previous version (`plugins.manage`).
+     *
+     * @deprecated Removed in 1.5.17. The player no longer keeps a previous
+     * version, so this always fails with `unsupported`. To go back to an older
+     * version of a third-party plugin, the user uninstalls it and installs that
+     * version's `.vxp`. See
+     * [Migrating off package rollback](../../docs/how-to/rollback-migration.md).
+     */
     rollback(id: string): Promise<PackageChange>;
     /** Every plugin: running, installed, and this run's development loads. No capability. */
     list(): Promise<PluginInfo[]>;

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

@@ -102,6 +102,11 @@ export interface PackageInfo {
     error: string | null;
     capabilities: string[];
     directory: string;
+    /**
+     * Always `null` from players that ship with SDK 1.5.16 or later.
+     *
+     * @deprecated Removed in 1.5.17: the player keeps no previous version.
+     */
     previousVersion: string | null;
     /** Player 0.2.0; absent from older players. */
     builtin?: boolean;
@@ -222,6 +227,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 +242,7 @@ export interface PlaybackStats {
         displayFps?: number | null;
         bitrate?: number | null;
         hwdec?: string | null;
+        decoding?: "hardware" | "software" | null;
         transfer?: string | null;
     } | null;
     audio: {
@@ -564,6 +572,10 @@ export declare function createWire(transport: Transport): {
             source?: WireSource;
             replace?: boolean;
         }) => Promise<PackageOperation>;
+        /**
+         * @deprecated Removed in 1.5.17. The player no longer has this method and
+         * rejects it with `unsupported` ("unknown package method").
+         */
         rollback: (id: string, expectedRevision: number, requestId: string) => Promise<PackageOperation>;
         operation: (operationId: string) => Promise<PackageOperation>;
         cancel: (operationId: string) => Promise<PackageOperation>;
@@ -590,7 +602,7 @@ export declare function createWire(transport: Transport): {
             sampleTime?: number;
         } | {
             kind: "rawJpeg" | "processedJpeg";
-            sampleTime?: number;
+            sampleTime? /** The path's keys (player 0.4.3). */: number;
             quality?: number;
         } | {
             kind: "rawMp4" | "processedMp4";

package/dist/wire.js

@@ -278,6 +278,10 @@ export function createWire(transport) {
                 ...(options.source === undefined ? {} : { source: options.source }),
                 ...(options.replace ? { replace: true } : {}),
             }),
+            /**
+             * @deprecated Removed in 1.5.17. The player no longer has this method and
+             * rejects it with `unsupported` ("unknown package method").
+             */
             rollback: (id, expectedRevision, requestId) => transport.request("packages.rollback", {
                 id,
                 expectedRevision,

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.14: full reference
+# @vestra-player/sdk 1.5.16: 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.
 
@@ -319,7 +319,7 @@ So `onDispose` cleanup must be quick and must not rely on the player. Media the
 plugin.dataDirectory is a writable directory for the plugin's own files (settings, caches, remembered folders). It needs no capability; the player creates it before it starts the plugin.
 
 - **One directory per installation.** Each fresh installation of a plugin gets its own directory (player 0.2.0). Installing the same id again from the same source is an upgrade and keeps the directory. Installing the same id from a different source, and confirming the replacement, gives the new plugin a new, empty directory; the old one is kept and reconnected if the user goes back to the first source later. A development load (`--plugin`) has a directory of its own.
-- **Kept** when the plugin is disabled, reloaded, upgraded or rolled back. Uninstalling deletes it only when the user asks for that (uninstall with `removeData: true`); otherwise reinstalling from the same source reconnects it.
+- **Kept** when the plugin is disabled, reloaded or upgraded. Uninstalling deletes it only when the user asks for that (uninstall with `removeData: true`); otherwise reinstalling from the same source reconnects it.
 - **The path's layout is not part of the API.** Do not derive another plugin's directory from yours; a plugin manager reads it from PluginInfo.dataDirectory.
 - **Write atomically.** Write to a temporary name and rename it, so a player that quits mid-write never leaves half a file; fall back to defaults when a file is missing or unreadable. For JSON settings use plugin.storage.json, which already does this (defaults, debounced atomic writes, a corrupt file moved aside).
 - Reading the property throws `unavailable` when the player could not provide a directory.
@@ -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.
 
@@ -1752,9 +1753,9 @@ Every member of `TestHost` is in the @vestra-player/sdk/testing reference.
 
 ## How-to: Publish a plugin
 
-**Goal:** your plugin appears in the player's plugin store, where users install, update and roll it back.
+**Goal:** your plugin appears in the player's plugin store, where users install, update and uninstall it.
 
-The store reads the official plugin repository, [vestrasys/vestra-player-plugins](https://github.com/vestrasys/vestra-player-plugins). Every change to it is a pull request to its `main` branch, and **a merge is a release**: there are no beta channels, and CI, the user's rollback and revocation are the safety net. Every plugin in it is a third-party plugin; only the plugins built into the player are official. The repository's [README](https://github.com/vestrasys/vestra-player-plugins#contributing-a-plugin) and [CONTRIBUTING](https://github.com/vestrasys/vestra-player-plugins/blob/main/CONTRIBUTING.md) hold the full rules; this page is the author's path through them.
+The store reads the official plugin repository, [vestrasys/vestra-player-plugins](https://github.com/vestrasys/vestra-player-plugins). Every change to it is a pull request to its `main` branch, and **a merge is a release**: there are no beta channels, and CI and revocation are the safety net. Every plugin in it is a third-party plugin; only the plugins built into the player are official. The repository's [README](https://github.com/vestrasys/vestra-player-plugins#contributing-a-plugin) and [CONTRIBUTING](https://github.com/vestrasys/vestra-player-plugins/blob/main/CONTRIBUTING.md) hold the full rules; this page is the author's path through them.
 
 #### Two ways in
 
@@ -1835,10 +1836,84 @@ After the merge, the repository's publish workflow builds the package, releases
 The store shows the newest version's manifest fields, so what you write there is the plugin's page:
 
 - **The list**: name and version, author and repository, the punchline. Search covers the name, id, author, punchline and tags; the list can be filtered by tag and sorted by name or by the date of the newest version. There are no download counts.
-- **The plugin's page**: the icon, name, author, punchline and the buttons (install, update, roll back, uninstall). Three tabs show the README, the changelog and the version history (version, release date, `minPlayerVersion`, and whether the version is current, incompatible or revoked; an older compatible version can be installed from there). A side column shows the version, the date, the license, a link to `sourceUrl` and the capabilities in plain words, the risky ones highlighted (the wording is the "Shown in the store as" column of Capabilities), with a fixed note that capabilities limit only the player API, not file or network access.
+- **The plugin's page**: the icon, name, author, punchline and the buttons (install, update, uninstall). Three tabs show the README, the changelog and the version history (version, release date, `minPlayerVersion`, and whether the version is current, incompatible or revoked). The player keeps no previous version, and the store has no action to install an older one: a user who wants an older version uninstalls the plugin and installs that version's `.vxp` (Migrating off package rollback). A side column shows the version, the date, the license, a link to `sourceUrl` and the capabilities in plain words, the risky ones highlighted (the wording is the "Shown in the store as" column of Capabilities), with a fixed note that capabilities limit only the player API, not file or network access.
 - **Before installing**, the user confirms a dialog that lists the capabilities; an update that adds capabilities lists the new ones. A plugin whose every version needs a newer player shows "needs Vestra Player x.y.z or later" instead of an install button.
 - **The README** is rendered as Markdown; relative links and images resolve against the README's own address, and remote images are shown for the official repository.
 
+## How-to: Migrating off package rollback (1.5.16)
+
+For plugins that manage other plugins (`plugins.manage`): stores, plugin managers, anything that calls packages.rollback or reads PluginInfo.previousVersion. A plugin that only uses its own API needs no change.
+
+#### What changed
+
+The player no longer keeps a previous version of a plugin. An upgrade replaces the package, so there is nothing to roll back to:
+
+- `packages.rollback(id)` always fails with `unsupported` (the player answers "unknown package method").
+- Every entry of `packages.list()` and `packages.onChange` has `previousVersion: null`.
+- Built-in plugins (`builtin: true`) run in place from the player installation. They can be disabled and enabled, never uninstalled or replaced; `uninstall` fails with `unsupported`. A built-in's `directory` is inside the installation (`<install resources>/plugins/<id>`) and read-only.
+- Third-party plugins can still be uninstalled.
+
+Why: built-ins now run from the read-only installation instead of a copy, and an upgrade replaces the package instead of keeping the old one beside it. Going back to an older version becomes an ordinary uninstall and install that the user starts.
+
+`TestHost` behaves the same way since 1.5.16, so tests show it too.
+
+#### 1. Remove rollback calls and `previousVersion` checks
+
+Before:
+
+```ts nocheck
+if (info.previousVersion !== null) showButton("Roll back", () => plugin.packages.rollback(info.id));
+```
+
+After: delete both. There is no replacement call; nothing on the player can restore an earlier package. Remove the button, menu item or command, and any state, text or test that depends on `previousVersion`.
+
+#### 2. Going back to an older version
+
+Managing plugins has exactly three operations: **install**, **uninstall** and **disable/enable**. There is no rollback, no "install older version" and no "Undo install".
+
+To go back to an older version, the user uninstalls the plugin and installs the older version's `.vxp` file themselves, as two ordinary operations. Do not offer an action that does both, an older-version install from a store, or an "Undo" after an install (the official store and the AI window drop theirs). Uninstalling without `removeData` keeps the plugin's data, and a reinstall from the same source reconnects to it; a `.vxp` file is a different source from a repository, so a plugin first installed from the store gets a new, empty data directory.
+
+#### 3. Remove "Undo install"
+
+Remove any Undo action after an install, its texts and translations, and the code that only served it: copies of installed `.vxp` files, remembered "last install" state, and tests of it. A user who wants a plugin gone uninstalls it.
+
+#### 4. Built-in plugins
+
+Check `builtin` before offering actions:
+
+```ts
+for (const info of await plugin.packages.list()) {
+  const actions = info.builtin
+    ? [info.state === "disabled" ? "Enable" : "Disable"]
+    : ["Disable", "Uninstall"];
+  console.log(info.id, actions);
+}
+```
+
+- Offer only disable and enable for a built-in (`packages.setEnabled`); never uninstall or install over it.
+- Never write into a built-in's `directory`, or into any plugin's `directory`: read `manifest.json` from it if you need to. A plugin writes only under its own plugin.dataDirectory.
+
+#### 5. Tests
+
+`TestHost` lists every plugin with `previousVersion: null`, whatever a test puts in `host.packages`, and rejects `packages.rollback` with `unsupported`. The `previousVersion` field of `host.packages` entries is deprecated and ignored; it stays required in 1.5.16 so that test data shaped like a `PluginInfo` keeps compiling, and goes in 1.5.17. A test that expected a rollback to succeed should now assert the rejection or be removed.
+
+#### Timeline
+
+| SDK | Player | What happens |
+| --- | --- | --- |
+| 1.5.16 | ships with it | `Packages.rollback` and `PluginInfo.previousVersion` (and the wire field) are `@deprecated`. The player and `TestHost` answer rollback with `unsupported` and list `previousVersion: null`. Code still compiles. |
+| 1.5.17 | — | Both symbols are removed. Remaining uses are TypeScript compile errors. |
+
+`apiVersion` stays `vestra/1` in both releases, as when 1.5.8 removed `PackageCandidate.trial()`.
+
+#### Before you hand it in
+
+- [ ] No call to `packages.rollback`; no UI or logic gated on `previousVersion`.
+- [ ] Built-ins offer only disable and enable.
+- [ ] Nothing writes into a plugin's `directory`.
+- [ ] No Undo after an install, no older-version install; older versions go through uninstall and a user-chosen `.vxp`.
+- [ ] Tests pass with SDK 1.5.16; the only deprecated name left in them is the `previousVersion: null` of `host.packages` test data.
+
 ## Guideline: Interface guidelines
 
 These are the rules the player's built-in plugins follow for their windows, panels and messages. Follow them and your plugin looks like part of the player. They assume you know the five surfaces from Windows, panels, settings pages, dialogs and the OSD; token names, sizes, fonts, icons and widgets are listed in Theme.
@@ -2080,6 +2155,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).
 
@@ -2124,6 +2200,8 @@ A plugin lists what it may do in the manifest's `capabilities` (Manifest). A cal
 - A file resolver (Resolvers.add with file types) also needs `producer.av`.
 - Without `events`, Player.state is read at start and after the plugin's own operations, and `onChange` listeners do not fire for changes made elsewhere.
 
+**Deprecated:** Packages.rollback in the `plugins.manage` row (since 1.5.16; removed in 1.5.17). The player keeps no previous version, so it always fails with `unsupported`; see Migrating off package rollback.
+
 #### Without a capability
 
 A member not in the table needs no capability: `plugin.tools`, `plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui` (images and Markdown), `plugin.i18n`, reading window.state, appearance.theme and packages.list. The table is `CAPABILITY_INFO`, which tests can import from `@vestra-player/sdk/testing` to check a manifest (CAPABILITY_INFO).
@@ -3059,6 +3137,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 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
@@ -3230,7 +3321,7 @@ interface Plugin extends Scope {
    * A writable directory for this plugin's own files (settings, caches,
    * remembered folders), created by the player before it starts the plugin.
    * Each installation has its own directory (player 0.2.0): it is kept across
-   * restarts, disabling, upgrades and rollbacks, and a reinstall of the same
+   * restarts, disabling and upgrades, and a reinstall of the same
    * id from a different source gets a new, empty one. It is deleted only by
    * `packages.uninstall(id, { removeData: true })`. No capability.
    *
@@ -3662,8 +3753,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 +5024,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 +5057,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;
@@ -5861,7 +5961,7 @@ interface PackageCandidate {
 
 ### PackageChangeStatus
 
-The progress of an install, rollback or uninstall.
+The progress of an install or uninstall.
 
 ```ts
 type PackageChangeStatus = "preparing" | "activating" | "restoring" | "committed" | "cancelled" | "failed" | "failedDegraded" | "tooLate";
@@ -5869,7 +5969,7 @@ type PackageChangeStatus = "preparing" | "activating" | "restoring" | "committed
 
 ### PackageChange
 
-An install, rollback or uninstall in progress. The SDK never submits a
+An install or uninstall in progress. The SDK never submits a
 change twice: after a lost reply it only queries the same request.
 
 ```ts
@@ -5905,9 +6005,14 @@ interface PluginInfo {
   error: string | null;
   /** Declared capabilities. */
   capabilities: string[];
-  /** The package directory (read its `manifest.json` for display fields). */
+  /**
+   * The package directory (read its `manifest.json` for display fields). A built-in's directory is inside the player installation (`<install resources>/plugins/<id>`) and read-only: a plugin writes only under its own Plugin.dataDirectory.
+   */
   directory: string;
-  /** The version a rollback would restore, `null` without one. */
+  /**
+   * Always `null`: the player no longer keeps a previous version, and an upgrade replaces the package.
+   * @deprecated Removed in 1.5.17. The player no longer keeps a previous version, so this is always `null`. See Migrating off package rollback.
+   */
   previousVersion: string | null;
   /** Shipped with the player: it can be disabled, not uninstalled or replaced. `false` from players before 0.2.0. */
   builtin: boolean;
@@ -5982,7 +6087,10 @@ interface Packages {
    * Validate a `.vxp` package file (`plugins.manage`, player 0.2.0): the same checks as Packages.validate after unpacking. Check the file's sha256 yourself before calling when you know it. A reserved id fails with `reserved`, as in Packages.validate.
    */
   validateArchive(file: string): Promise<PackageCandidate>;
-  /** Restore a plugin's previous version (`plugins.manage`). */
+  /**
+   * Formerly restored a plugin's previous version (`plugins.manage`).
+   * @deprecated Removed in 1.5.17. The player no longer keeps a previous version, so this always fails with `unsupported`. To go back to an older version of a third-party plugin, the user uninstalls it and installs that version's `.vxp`. See Migrating off package rollback.
+   */
   rollback(id: string): Promise<PackageChange>;
   /** Every plugin: running, installed, and this run's development loads. No capability. */
   list(): Promise<PluginInfo[]>;
@@ -6456,7 +6564,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;
@@ -7301,7 +7411,7 @@ class TestHost implements Transport {
     overlay: Map<string, string[]>;
   };
   /**
-   * What `packages.list` reports; `setEnabled`, `uninstall` and `install` update it. `builtin`, `source` and `dataDirectory` are optional here (default `false`, `null`, `null`).
+   * What `packages.list` reports; `setEnabled`, `uninstall` and `install` update it. `builtin`, `source` and `dataDirectory` are optional here (default `false`, `null`, `null`). Like the player, the host lists every plugin with `previousVersion: null` and answers `packages.rollback` with `unsupported` (since 1.5.16).
    */
   packages: {
     /** The plugin's manifest id. */
@@ -7318,7 +7428,10 @@ class TestHost implements Transport {
     capabilities: string[];
     /** The package directory. */
     directory: string;
-    /** The version a rollback would restore, `null` without one. */
+    /**
+     * Ignored: `packages.list` always reports `null`. Still required in 1.5.16 so that test data shaped like a `PluginInfo` keeps compiling.
+     * @deprecated Removed in 1.5.17 with `PluginInfo.previousVersion`.
+     */
     previousVersion: string | null;
     /** Shipped with the player: `uninstall` and `install` are `unsupported`. */
     builtin?: boolean;
@@ -8011,10 +8124,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 +8157,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.16: 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: L2100–2163.
 
 **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: L2164–2208.
 
-**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: L6759.
 
 **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 L3105.
 
 ## 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; Migrating off package rollback (1.5.16) L1843–1916
+- Guidelines: Interface guidelines L1917–2001; Menu guidelines L2002–2099
+- Reference: Manifest L2100–2163; Capabilities L2164–2208; Limits L2209–2303; Commands, menus and bindings L2304–2772; Platforms L2773–2801; Theme L2802–3006; Command line L3007–3062
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3063–6594
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6595–7922
 
 ## 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 L3297, Scope L3166, PluginError L3105, Disposable L3078
+- Commands L3509; Windows L3714; Panels L4357; Dialogs L4643; Player L5091; video: VideoFilter L5356, VideoView L5419, RenderOptions L5461; audio: AudioFilter L5380; Subtitles L5559; media: MediaCapture L5719; Resolvers L5824; Packages L6069; Osd L5292; Host L5240; Clipboard L6189; Power L6209; Tools L6242; Storage L6285; System L6308; Secrets L6326; window: MainWindow L4480; App L4561; Bindings L6159; Ui L3601; Timeline L4437; Drops L4013; Appearance L4042; I18n L4184; Settings L4290.
 
 ## 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. L8346–8435
+- blur: A tool window with one slider that blurs the playing video. L8436–8697
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8698–9030
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9031–9215
+- panel-menu: A sidebar panel with its own right-click menu. L9216–9421
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9422–9581
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9582–9745
+- markdown: A window that shows a Markdown document. L9746–9940
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L9941–10108
 
 ## 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.16",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {