@vestra-player/sdk 1.5.15 → 1.5.17

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.5.17
+
+**Package rollback is removed**, as announced in 1.5.16: the player keeps no previous plugin version. `apiVersion` stays `vestra/1` (a patch release, as when 1.5.8 removed `PackageCandidate.trial()`); plugins that do not manage other plugins need no change. A plugin manager that still calls `rollback` or reads `previousVersion` no longer compiles. Migration: [Migrating off package rollback](docs/how-to/rollback-migration.md).
+
+- **Removed: `Packages.rollback`** and the wire method `packages.rollback`. The player already answers the method with `unsupported` ("unknown package method"). To go back to an older version of a third-party plugin, the user uninstalls it and installs that version's `.vxp`.
+- **Removed: `PluginInfo.previousVersion`** and the wire field `PackageInfo.previousVersion`; `packages.list` and `packages.changed` no longer carry it.
+- **Removed from `CAPABILITY_INFO["plugins.manage"].apis`**: `"Packages.rollback"`; the capability is unchanged otherwise.
+- **`TestHost`**: `host.packages` entries have no `previousVersion` field (delete it from test data), and there is no `packages.rollback` handler.
+- Unchanged: `revisionConflict`, and the `restoring` and `failedDegraded` statuses of `PackageChange`, which belong to recovery from a failed install.
+- Docs: the Capabilities reference loses the deprecation note; *Migrating off package rollback* says what 1.5.17 removed; `llms.txt` and `llms-full.txt` regenerated.
+
+## 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/capabilities.js

@@ -130,7 +130,6 @@ export const CAPABILITY_INFO = Object.freeze({
         apis: [
             "Packages.validate",
             "Packages.validateArchive",
-            "Packages.rollback",
             "Packages.setEnabled",
             "Packages.uninstall",
         ],

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,7 +126,6 @@ export const packages = (scope) => ({
         const checked = await scope.runtime.host.packages.validateArchive(path);
         return candidate(scope, path, checked);
     },
-    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) {
         const watch = scope.runtime.on("packages.changed", (data) => scope.run(listener, data.map(info)), null);
@@ -152,7 +151,6 @@ const info = (plugin) => Object.freeze({
     error: plugin.error,
     capabilities: [...plugin.capabilities],
     directory: plugin.directory,
-    previousVersion: plugin.previousVersion,
     builtin: plugin.builtin === true,
     source: plugin.source ? Object.freeze({ ...plugin.source }) : null,
     dataDirectory: plugin.dataDirectory ?? null,

package/dist/plugin/testing.d.ts

@@ -1328,8 +1328,6 @@ export declare class TestHost implements Transport {
         capabilities: string[];
         /** The package directory. */
         directory: string;
-        /** The version a rollback would restore, `null` without one. */
-        previousVersion: string | null;
         /** Shipped with the player: `uninstall` and `install` are `unsupported`. */
         builtin?: boolean;
         /** Where it was installed from. */

package/dist/plugin/testing.js

@@ -1919,7 +1919,7 @@ export class TestHost {
      */
     setPackages(list) {
         this.packages = list;
-        this.emit("packages.changed", structuredClone(list));
+        this.emit("packages.changed", structuredClone(this.packages));
     }
     #split(key) {
         const at = key.indexOf("/");
@@ -3205,9 +3205,6 @@ export class TestHost {
                 error: null,
                 capabilities: [...manifest.capabilities],
                 directory: `/test-host/packages/${manifest.id}`,
-                previousVersion: entry && identity(entry.source) === identity(source)
-                    ? entry.version
-                    : null,
                 builtin: false,
                 source,
                 dataDirectory: entry?.dataDirectory ?? null,

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,10 +4725,13 @@ 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. */
-    previousVersion: string | null;
     /**
      * Shipped with the player: it can be disabled, not uninstalled or
      * replaced. `false` from players before 0.2.0.
@@ -4827,8 +4830,6 @@ export interface Packages {
      * fails with `reserved`, as in {@link Packages.validate}.
      */
     validateArchive(file: string): Promise<PackageCandidate>;
-    /** Restore a plugin's previous version (`plugins.manage`). */
-    rollback(id: string): Promise<PackageChange>;
     /** Every plugin: running, installed, and this run's development loads. No capability. */
     list(): Promise<PluginInfo[]>;
     /** The new list after any start, stop, failure, install or uninstall. No capability. */

package/dist/wire.d.ts

@@ -102,7 +102,6 @@ export interface PackageInfo {
     error: string | null;
     capabilities: string[];
     directory: string;
-    previousVersion: string | null;
     /** Player 0.2.0; absent from older players. */
     builtin?: boolean;
     source?: WireSource | null;
@@ -567,7 +566,6 @@ export declare function createWire(transport: Transport): {
             source?: WireSource;
             replace?: boolean;
         }) => Promise<PackageOperation>;
-        rollback: (id: string, expectedRevision: number, requestId: string) => Promise<PackageOperation>;
         operation: (operationId: string) => Promise<PackageOperation>;
         cancel: (operationId: string) => Promise<PackageOperation>;
         list: () => Promise<PackageInfo[]>;

package/dist/wire.js

@@ -278,11 +278,6 @@ export function createWire(transport) {
                 ...(options.source === undefined ? {} : { source: options.source }),
                 ...(options.replace ? { replace: true } : {}),
             }),
-            rollback: (id, expectedRevision, requestId) => transport.request("packages.rollback", {
-                id,
-                expectedRevision,
-                requestId,
-            }),
             operation: (operationId) => transport.request("packages.operation", {
                 operationId,
             }),

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.15: full reference
+# @vestra-player/sdk 1.5.17: 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, removed in 1.5.17)
+
+For plugins that manage other plugins (`plugins.manage`): stores, plugin managers, anything that called `packages.rollback` or read `PluginInfo.previousVersion`. Both were deprecated in 1.5.16 and **removed in 1.5.17**: with 1.5.17 a remaining use is a TypeScript compile error. 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:
+
+- There is no `packages.rollback`: the player answers the wire method with `unsupported` ("unknown package method"), and SDK 1.5.17 no longer has it.
+- `packages.list()` and `packages.onChange` entries have no `previousVersion` (always `null` with SDK 1.5.16, removed in 1.5.17).
+- 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, 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`. With SDK 1.5.17 the compiler finds every remaining use.
+
+#### 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
+
+With SDK 1.5.17, `host.packages` entries have no `previousVersion` field: delete `previousVersion: null` (or any value) from test data, or the test no longer compiles. `TestHost` has no `packages.rollback`. Remove tests that exercised a rollback; there is nothing left to assert. (With 1.5.16 the field was still required but ignored, and `TestHost` answered rollback with `unsupported`.)
+
+#### 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 | ships with it | **Removed:** `Packages.rollback`, `PluginInfo.previousVersion`, the wire method `packages.rollback` and the wire field `previousVersion`, `TestHost`'s `previousVersion` field and its `packages.rollback` handler, and `Packages.rollback` in the `plugins.manage` capability. 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 compile and pass with SDK 1.5.17; no `previousVersion` is left in `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.
@@ -2102,7 +2176,7 @@ A plugin lists what it may do in the manifest's `capabilities` (Manifest). A cal
 | `ui.window` | Windows.create | — | Open tool windows |  |
 | `ui.mount` | Panels.mount, Panels.bottom, Panels.sidebar, Panels.backdrop, PanelSlot.onChange, Panel.onChange, BackdropSlot.onChange | — | Show panels in the bottom bar, the sidebar or behind the video |  |
 | `ui.dialog` | Dialogs.confirm, Dialogs.openFile, Dialogs.openFiles, Dialogs.openDirectory, Dialogs.saveFile | — | Show file pickers and confirmations |  |
-| `plugins.manage` | Packages.validate, Packages.validateArchive, Packages.rollback, Packages.setEnabled, Packages.uninstall | — | Install, uninstall and disable other plugins | yes |
+| `plugins.manage` | Packages.validate, Packages.validateArchive, Packages.setEnabled, Packages.uninstall | — | Install, uninstall and disable other plugins | yes |
 | `processing.video` | Plugin.video.filter, Plugin.video.view, Plugin.video.render | `playback.read` | Process the picture (filters, shaders) |  |
 | `processing.audio` | Plugin.audio.filter | `playback.read`, `events` | Process the sound |  |
 | `subtitles.read` | Subtitles.state, Subtitles.onChange, Subtitles.refresh | — | Read subtitles |  |
@@ -3070,7 +3144,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 +3319,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 +5959,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 +5967,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,10 +6003,10 @@ 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. */
-  previousVersion: string | null;
   /** Shipped with the player: it can be disabled, not uninstalled or replaced. `false` from players before 0.2.0. */
   builtin: boolean;
   /** Where an installed plugin came from; `null` for development loads. */
@@ -6006,8 +6080,6 @@ 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`). */
-  rollback(id: string): Promise<PackageChange>;
   /** Every plugin: running, installed, and this run's development loads. No capability. */
   list(): Promise<PluginInfo[]>;
   /** The new list after any start, stop, failure, install or uninstall. No capability. */
@@ -7344,8 +7416,6 @@ class TestHost implements Transport {
     capabilities: string[];
     /** The package directory. */
     directory: string;
-    /** The version a rollback would restore, `null` without one. */
-    previousVersion: string | null;
     /** Shipped with the player: `uninstall` and `install` are `unsupported`. */
     builtin?: boolean;
     /** Where it was installed from. */

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.17: 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**
 
@@ -60,7 +60,7 @@ export default async function activate(plugin: Plugin) {
 - `ui.window`: Windows.create
 - `ui.mount`: Panels.mount/bottom/sidebar/backdrop, PanelSlot/Panel/BackdropSlot.onChange
 - `ui.dialog`: Dialogs.confirm/openFile/openFiles/openDirectory/saveFile
-- `plugins.manage`: Packages.validate/validateArchive/rollback/setEnabled/uninstall
+- `plugins.manage`: Packages.validate/validateArchive/setEnabled/uninstall
 - `processing.video`: Plugin.video.filter/video.view/video.render (also `playback.read`)
 - `processing.audio`: Plugin.audio.filter (also `playback.read`, `events`)
 - `subtitles.read`: Subtitles.state/onChange/refresh
@@ -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–2206.
 
-**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: L6747.
 
 **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 L3103.
 
 ## 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, removed in 1.5.17) L1843–1916
+- Guidelines: Interface guidelines L1917–2001; Menu guidelines L2002–2099
+- Reference: Manifest L2100–2163; Capabilities L2164–2206; Limits L2207–2301; Commands, menus and bindings L2302–2770; Platforms L2771–2799; Theme L2800–3004; Command line L3005–3060
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3061–6582
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6583–7905
 
 ## 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 L3295, Scope L3164, PluginError L3103, Disposable L3076
+- Commands L3507; Windows L3712; Panels L4355; Dialogs L4641; Player L5089; video: VideoFilter L5354, VideoView L5417, RenderOptions L5459; audio: AudioFilter L5378; Subtitles L5557; media: MediaCapture L5717; Resolvers L5822; Packages L6062; Osd L5290; Host L5238; Clipboard L6177; Power L6197; Tools L6230; Storage L6273; System L6296; Secrets L6314; window: MainWindow L4478; App L4559; Bindings L6147; Ui L3599; Timeline L4435; Drops L4011; Appearance L4040; I18n L4182; Settings L4288.
 
 ## 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. L8329–8418
+- blur: A tool window with one slider that blurs the playing video. L8419–8680
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8681–9013
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9014–9198
+- panel-menu: A sidebar panel with its own right-click menu. L9199–9404
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9405–9564
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9565–9728
+- markdown: A window that shows a Markdown document. L9729–9923
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L9924–10091
 
 ## Optional
 

package/package.json

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