@vestra-player/sdk 1.5.15 → 1.5.16

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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.

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/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

@@ -1862,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. */
@@ -1919,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("/");
@@ -3153,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)
@@ -3205,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,
@@ -3235,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

@@ -90,7 +90,7 @@ export interface Disposable {
  * | `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. |
+ * | `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. |
@@ -336,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.
      *
@@ -4693,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 {
@@ -4725,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
@@ -4827,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/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;
@@ -567,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>;
@@ -593,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.15: 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.
@@ -1753,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
 
@@ -1836,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.
@@ -2126,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).
@@ -3070,7 +3146,7 @@ change).
 | `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. |
+| `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. |
@@ -3245,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.
    *
@@ -5885,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";
@@ -5893,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
@@ -5929,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;
@@ -6006,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[]>;
@@ -7327,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. */
@@ -7344,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;

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @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.
+> @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: L2026–2089.
+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: L2090–2132.
+- 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: L1588–1753; TestHost: L6675.
+**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,39 +106,39 @@ 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 L3029.
+- 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–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
+- 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 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.
+- 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. 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
+- 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
 

package/package.json

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