@vestra-player/sdk 1.5.54 → 1.5.57

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.5.57
+
+**Who must change: nobody.** The first npm release with 1.5.56's fix: no change to the TypeScript API or the wire, `apiVersion` stays `vestra/1`, no new capability, no player version needed.
+
+- **1.5.56 never reached npm.** Its tag was pushed, but the release run (41502365359) skipped `publish` because GitHub never gave its two macOS jobs a hosted runner (capacity) and they were cancelled. 1.5.57 publishes the same code: `appearance.onChange` and `resolvers.onFileTypesChange` hear a change the player woke the plugin for, and the session-storage clearing docs, as described under [1.5.56](#1556). Install 1.5.57; there is no `@vestra-player/sdk@1.5.56` on npm.
+- _Release process_: runner capacity no longer blocks a release (product-owner ruling, 2026-11-02). `release.yml` publishes once `verify`, `static`, `build`, `docs` and the Ubuntu and Windows tests and examples pass; macOS tests and examples still run on every release as `test-macos`, beside `publish` and without gating it. `_test.yml` takes an `os` input (a JSON array of runner labels, all three by default), so pull requests and `main` still test and gate on Ubuntu, Windows and macOS as before. [Maintaining › Releasing](docs/maintaining.md#releasing) says so.
+
+## 1.5.56
+
+**Who must change: nobody.** A fix: no change to the TypeScript API or the wire, `apiVersion` stays `vestra/1`, no new capability, no player version needed.
+
+- **`appearance.onChange` and `resolvers.onFileTypesChange` hear a change the player woke the plugin for.** A plugin the player stopped and starts again to deliver a palette or file-type change ([Idle plugins are stopped](docs/explanation/plugins.md#idle-plugins-are-stopped)) read the new value with `window.state` at start; the held `appearance.changed` or `resolvers.fileTypes` that followed compared equal to it, so the listeners never ran. The SDK now compares an event with what the listeners last heard, not with the value read at start: they hear the change once, and the same value again is still not a change. The player sends `resolvers.fileTypes` only when the list changed. It sends `appearance.changed` when the theme or the language changed, both values each time; an event whose language differs from the last one the SDK saw is a language change, and as before does not call `onChange` unless the theme differs too (also for the echo of the plugin's own `setLanguage`). One case remains: a plugin the player woke for a language change alone cannot tell it from a theme change, since the event does not say what changed, and its `onChange` may hear the unchanged theme once. A field naming the change could be added to the event later without breaking anything. `appearance.theme`, `resolvers.fileTypes` and views read the same values as before. `packages.onChange` and `bindings.onChange` (the other two events that wake a plugin) never compared, and are unchanged.
+- _Docs_: when session storage is cleared, corrected against the player: also when a store or another plugin with `plugins.manage` disables the plugin (`packages.setEnabled(id, false)`, or an update installed with `enabled: false`, player 0.6.4), and when an earlier installation kept for a later reinstall (after a `replace`) is dropped because the player keeps only so many; [How a plugin runs › Stopping](docs/explanation/plugins.md#stopping) names other plugins with `plugins.manage` too. `SessionStorage`, [How a plugin runs › Restarts](docs/explanation/plugins.md#restarts-activate-can-run-more-than-once) and [Store a plugin's data](docs/how-to/store-data.md) say so. `Appearance.onChange` and `Resolvers.onFileTypesChange` describe the wake.
+
+## 1.5.55
+
+**Who must change: nobody, but check `TestHost` tests that update a disabled plugin.** Additive: `InstallOptions` gains `enabled` and `TestHost` gains `installKeepsDisabled`, `apiVersion` stays `vestra/1`, no new capability, and existing code still compiles. Older players ignore the option, and an install there always enables the plugin. One `TestHost` behaviour change at run time: like player 0.6.4, it now keeps a `disabled` entry disabled when the plugin under test installs an update or reinstall over it without `enabled`, where it used to make it `running`. A test that expects the update to run (the player's Store test did) sets `host.installKeepsDisabled = false` to keep playing players up to 0.6.3, or asserts the new rule; a test that covers both runs once with each.
+
+- **Choose whether an installed plugin runs** (`candidate.install({ enabled })`). Planned for player 0.6.4 (not released yet), where an update or reinstall (from any source, `replace` included) keeps the installed plugin's state when `enabled` is left out: a plugin the user or a store disabled stays disabled, and only its files are installed. A first install runs as before. `true` enables and starts it, for a store that disabled a revoked version and installs the update that fixes it (if the new version fails to start, the old one is restored, still disabled); `false` installs it disabled, stopping a running version and dropping its session values as `setEnabled(id, false)` does. Built-in plugins always run. The SDK sends `enabled` only when given and refuses anything but a boolean with `invalid` before sending. On players up to 0.6.3 the option is ignored and every install runs; call `packages.setEnabled` after the install is committed when the state matters there.
+- **`TestHost`** models player 0.6.4 by default: a first install is `running`, an update of a `disabled` entry stays `disabled` unless `enabled: true`, `enabled: false` installs it `disabled`, and a non-boolean `enabled` on the wire is `invalid` (`null` reads as absent, as in the player). `installKeepsDisabled = false` plays players up to 0.6.3 instead: every install is `running` and `enabled` is ignored. `packageCalls` records `install`'s `enabled` when it was given.
+- **Stop reasons, corrected** (SDK 1.5.54 docs, from the player's implementation for 0.6.4, still planned). `upgrade` also covers a new version stopped because its install was cancelled (the previous version comes back). `idle` comes only with lazy activation, which is off by default (`VESTRA_LAZY=1`), and also parks a plugin whose first run it judges lazy right after it is ready, not only after a while without use. `failed` is not sent for a full input queue: an own process is killed, and a member's full queue restarts the shared runner as a whole, as does an unreadable line from the runner itself. In those cases, and when an own process fails to activate or the process has already exited, the plugin gets no stop at all and its `onDispose` cleanups do not run. `host-lost` is not proof of a crash: player 0.6.4 sends `quit` on a normal exit, while an older player could close its pipes first when its window closed. [How a plugin runs › Restarts](docs/explanation/plugins.md#restarts-activate-can-run-more-than-once) now states as fact that plugins sharing one process are restarted together (player 0.5.6 and later). `StopReason`, [The plugin model](docs/explanation/plugins.md#stopping) and [Host and Node](docs/explanation/host-and-node.md#stopping-a-plugin) say so.
+- _Docs_: `InstallOptions.enabled`, `PackageCandidate.install` (with an example; the `replace` example no longer promises a running plugin), `TestHost.candidates` and `TestHost.installKeepsDisabled` describe it.
+
 ## 1.5.54
 
 **Who must change: nobody, but check cleanup functions passed directly to `onDispose`.** Additive: `Plugin.stopReason`, the types `StopReason` and `DisposeInfo`, an optional argument for `onDispose` cleanups, `TestHost.previousCrash`, an optional `code` for `TestHost.failVideoShaders` and `stop({ reason })` / `disconnect()` from `startPlugin`; `apiVersion` stays `vestra/1`, no new capability, and existing code still compiles. One runtime difference: with this SDK in the player (or in `TestHost`) an `onDispose` cleanup is called with one argument, the `DisposeInfo`. A function that takes optional parameters of its own and is passed directly now receives it as its first argument: `plugin.onDispose(controller.abort.bind(controller))` aborts with the `DisposeInfo` as the abort reason, `onDispose(save)` with `save(force?: boolean)` gets an object as `force`. Wrap such a function (`() => controller.abort()`). The stop reasons are planned for player 0.6.4; `previous-crash` comes from player 0.6.3.

package/dist/plugin/appearance.js

@@ -18,12 +18,34 @@ class AppearanceService {
     /** The saved interface language (the next start's). */
     language;
     #listeners = new Set();
+    /**
+     * The theme listeners last heard (or the last event's), not the one read
+     * at start: a plugin woken from standby reads the new theme from
+     * `window.state`, then gets the `appearance.changed` the player held for
+     * it, and its listeners still hear that change. Left unset until the
+     * first event on purpose: set from the start-up read, it would hide that
+     * held change again.
+     */
+    #notified;
+    /**
+     * The language as the start-up read and later events carried it (not
+     * `language`, which the plugin's own `setLanguage` changes before its
+     * echo arrives). The player sends `appearance.changed` once per change
+     * of the theme or of the language, each with both values: an event whose
+     * language differs from this one is a language change, and its theme is
+     * compared with `theme` as before. Only a newest event that repeats the
+     * start-up language is taken for a theme change; a plugin woken for a
+     * language change gets that too, so its listeners may hear the unchanged
+     * theme once (the event does not say what changed).
+     */
+    #eventLanguage;
     #started = false;
     constructor(runtime) {
         this.#runtime = runtime;
         this.theme =
             windowOf(runtime).appearance ?? "vestra";
         this.language = preference(windowOf(runtime).language) ?? "system";
+        this.#eventLanguage = this.language;
     }
     start() {
         if (this.#started)
@@ -33,22 +55,47 @@ class AppearanceService {
         this.#runtime.on("appearance.changed", (data) => {
             const event = data;
             const language = preference(event?.language);
+            // Older players send no language: their events are theme changes.
+            const languageChanged = language !== undefined && language !== this.#eventLanguage;
+            if (language)
+                this.#eventLanguage = language;
             if (language && language !== this.language) {
                 this.language = language;
                 this.#runtime.invalidate();
             }
             const theme = event?.theme;
-            if (theme && THEMES.includes(theme))
+            if (!theme || !THEMES.includes(theme))
+                return;
+            if (languageChanged) {
+                // The theme came along unchanged (or this plugin set it already).
                 this.accept(theme);
+                this.#notified = theme;
+            }
+            else
+                this.changed(theme);
         }, "events", true);
     }
+    /** A theme change event: listeners hear it unless they already did. */
+    changed(theme) {
+        const changed = theme !== this.theme;
+        this.theme = theme;
+        if (theme !== this.#notified)
+            this.#notify(theme);
+        if (changed)
+            this.#runtime.invalidate();
+    }
+    /** After this plugin's own `set`: only a change from the current theme. */
     accept(theme) {
         if (theme === this.theme)
             return;
         this.theme = theme;
+        this.#notify(theme);
+        this.#runtime.invalidate();
+    }
+    #notify(theme) {
+        this.#notified = theme;
         for (const listener of [...this.#listeners])
             listener(theme);
-        this.#runtime.invalidate();
     }
     watch(listener) {
         this.#listeners.add(listener);

package/dist/plugin/packages.js

@@ -83,9 +83,11 @@ function installOptions(options) {
         return {};
     if (typeof options !== "object" || options === null)
         throw failure("invalid", "install options must be an object");
-    const { source, replace } = options;
+    const { source, replace, enabled } = options;
     if (replace !== undefined && typeof replace !== "boolean")
         throw failure("invalid", "replace must be a boolean");
+    if (enabled !== undefined && typeof enabled !== "boolean")
+        throw failure("invalid", "enabled must be a boolean");
     if (source !== undefined) {
         const kinds = ["repository", "link", "file", "workshop"];
         if (typeof source !== "object" ||
@@ -99,6 +101,7 @@ function installOptions(options) {
     return {
         ...(source === undefined ? {} : { source: { ...source } }),
         ...(replace ? { replace: true } : {}),
+        ...(enabled === undefined ? {} : { enabled }),
     };
 }
 function candidate(scope, directory, checked) {

package/dist/plugin/resolvers.js

@@ -17,6 +17,14 @@ class FileTypesService {
     #runtime;
     types;
     #listeners = new Set();
+    /**
+     * The list listeners last heard, not the one read at start: a plugin
+     * woken from standby reads the new list from `window.state`, then gets
+     * the `resolvers.fileTypes` the player held for it, and its listeners
+     * still hear that change. The player sends the event only when the list
+     * changed, so a first event is always news to the listeners.
+     */
+    #notified;
     #started = false;
     constructor(runtime) {
         this.#runtime = runtime;
@@ -30,7 +38,7 @@ class FileTypesService {
         this.#runtime.on("resolvers.fileTypes", (data) => {
             const types = data?.fileTypes;
             if (Array.isArray(types) && types.every((t) => typeof t === "string"))
-                this.accept(types);
+                this.changed(types);
         }, "events", true);
         // What changed between the start-up read and the subscription.
         const window = windowOf(this.#runtime);
@@ -39,16 +47,33 @@ class FileTypesService {
                 this.accept(window.fileTypes, this.#runtime.can("events"));
         });
     }
-    /** `notify`: false without `events`, whose listeners never fire. */
+    /** From `resolvers.fileTypes`: listeners hear it unless they already did. */
+    changed(types) {
+        const changed = !sameTypes(types, this.types);
+        if (changed)
+            this.types = Object.freeze([...types]);
+        if (!this.#notified || !sameTypes(types, this.#notified))
+            this.#notify(types);
+        if (changed)
+            this.#runtime.invalidate();
+    }
+    /**
+     * From a `window.state` read: only a change from the current list.
+     * `notify`: false without `events`, whose listeners never fire.
+     */
     accept(types, notify = true) {
         if (sameTypes(types, this.types))
             return;
         this.types = Object.freeze([...types]);
         if (notify)
-            for (const listener of [...this.#listeners])
-                listener([...types]);
+            this.#notify(types);
         this.#runtime.invalidate();
     }
+    #notify(types) {
+        this.#notified = Object.freeze([...types]);
+        for (const listener of [...this.#listeners])
+            listener([...types]);
+    }
     watch(listener) {
         this.#listeners.add(listener);
         const held = this.#runtime.hold("resolvers.fileTypes");

package/dist/plugin/testing.d.ts

@@ -2436,7 +2436,7 @@ export declare class TestHost implements Transport {
         method: "setEnabled" | "reload" | "uninstall" | "install";
         /** The target plugin id. */
         id: string;
-        /** `setEnabled`'s value. */
+        /** `setEnabled`'s value, or `install`'s `enabled` option when given. */
         enabled?: boolean;
         /** `uninstall`'s `removeData` option. */
         removeData?: boolean;
@@ -2450,7 +2450,13 @@ export declare class TestHost implements Transport {
      * `.vxp` file) → its manifest. Other paths fail with `missing`. `install`
      * adds or upgrades the entry in {@link TestHost.packages} following the
      * player's source rules: the same source upgrades, another source needs
-     * `replace` (`conflict` otherwise), a built-in id is `unsupported`.
+     * `replace` (`conflict` otherwise), a built-in id is `unsupported`. As
+     * player 0.6.4 (planned), the installed entry's `state` follows
+     * {@link "@vestra-player/sdk"!InstallOptions.enabled}: a first install
+     * runs, an update of a `disabled` entry stays `disabled` unless `enabled`
+     * is `true`, and `enabled: false` installs it `disabled`. Set
+     * {@link TestHost.installKeepsDisabled} to `false` for the older players'
+     * rule (every install runs).
      *
      * @example Offer a package file the plugin can install
      * The plugin can validate and install `/downloads/someone.demo-1.0.0.vxp`
@@ -2467,6 +2473,32 @@ export declare class TestHost implements Transport {
      * ```
      */
     readonly candidates: Map<string, PackageManifest>;
+    /**
+     * Which player's install rule `packages.install` plays. `true` (default,
+     * SDK 1.5.55): player 0.6.4 (planned), where an update or reinstall
+     * keeps a `disabled` plugin disabled unless the plugin passes
+     * {@link "@vestra-player/sdk"!InstallOptions.enabled}. `false`: players
+     * up to 0.6.3, where every install runs the plugin and `enabled` is
+     * ignored (it is still checked and recorded in
+     * {@link TestHost.packageCalls}). A test written for the older rule that
+     * updates a disabled plugin sets it to `false`; one that keeps testing
+     * both runs once with each.
+     *
+     * @example Keep a test written for players up to 0.6.3
+     * The plugin under test installs an update over a plugin the user
+     * disabled and expects it to run afterwards, as players up to 0.6.3 do.
+     * With `false` the host plays that rule; the default plays player 0.6.4,
+     * where the update stays disabled.
+     * ```ts
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.installKeepsDisabled = false; // every install runs, as before 0.6.4
+     * ```
+     *
+     * @capability None.
+     * @since 1.5.55
+     */
+    installKeepsDisabled: boolean;
     /**
      * Remote images (`plugin.ui.markdown`, `plugin.ui.remoteImage`): address
      * → a local PNG or JPEG file served for it, or `null` for a failing

package/dist/plugin/testing.js

@@ -3099,7 +3099,13 @@ export class TestHost {
      * `.vxp` file) → its manifest. Other paths fail with `missing`. `install`
      * adds or upgrades the entry in {@link TestHost.packages} following the
      * player's source rules: the same source upgrades, another source needs
-     * `replace` (`conflict` otherwise), a built-in id is `unsupported`.
+     * `replace` (`conflict` otherwise), a built-in id is `unsupported`. As
+     * player 0.6.4 (planned), the installed entry's `state` follows
+     * {@link "@vestra-player/sdk"!InstallOptions.enabled}: a first install
+     * runs, an update of a `disabled` entry stays `disabled` unless `enabled`
+     * is `true`, and `enabled: false` installs it `disabled`. Set
+     * {@link TestHost.installKeepsDisabled} to `false` for the older players'
+     * rule (every install runs).
      *
      * @example Offer a package file the plugin can install
      * The plugin can validate and install `/downloads/someone.demo-1.0.0.vxp`
@@ -3116,6 +3122,32 @@ export class TestHost {
      * ```
      */
     candidates = new Map();
+    /**
+     * Which player's install rule `packages.install` plays. `true` (default,
+     * SDK 1.5.55): player 0.6.4 (planned), where an update or reinstall
+     * keeps a `disabled` plugin disabled unless the plugin passes
+     * {@link "@vestra-player/sdk"!InstallOptions.enabled}. `false`: players
+     * up to 0.6.3, where every install runs the plugin and `enabled` is
+     * ignored (it is still checked and recorded in
+     * {@link TestHost.packageCalls}). A test written for the older rule that
+     * updates a disabled plugin sets it to `false`; one that keeps testing
+     * both runs once with each.
+     *
+     * @example Keep a test written for players up to 0.6.3
+     * The plugin under test installs an update over a plugin the user
+     * disabled and expects it to run afterwards, as players up to 0.6.3 do.
+     * With `false` the host plays that rule; the default plays player 0.6.4,
+     * where the update stays disabled.
+     * ```ts
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.installKeepsDisabled = false; // every install runs, as before 0.6.4
+     * ```
+     *
+     * @capability None.
+     * @since 1.5.55
+     */
+    installKeepsDisabled = true;
     /**
      * Remote images (`plugin.ui.markdown`, `plugin.ui.remoteImage`): address
      * → a local PNG or JPEG file served for it, or `null` for a failing
@@ -5105,6 +5137,10 @@ export class TestHost {
             if (source.kind === "bundled")
                 throw new HostError("invalid", "source bundled is reserved");
             const replace = p.replace === true;
+            // As player 0.6.4: `enabled` is a boolean, or absent (`null` too).
+            const requested = p.enabled ?? undefined;
+            if (requested !== undefined && typeof requested !== "boolean")
+                throw new HostError("invalid", "enabled must be a boolean");
             const entry = this.packages.find((each) => each.id === manifest.id);
             if (entry?.builtin)
                 throw new HostError("unsupported", "built-in plugins are updated with the player");
@@ -5120,12 +5156,19 @@ export class TestHost {
                 id: manifest.id,
                 source,
                 replace,
+                ...(requested === undefined ? {} : { enabled: requested }),
             });
+            // As player 0.6.4: a first install runs; an update or reinstall (any
+            // source, `replace` included) keeps a disabled plugin disabled unless
+            // `enabled` is given. Players up to 0.6.3 run every install.
+            const enabled = !this.installKeepsDisabled
+                ? true
+                : (requested ?? entry?.state !== "disabled");
             const next = {
                 id: manifest.id,
                 version: manifest.version,
                 origin: "installed",
-                state: "running",
+                state: enabled ? "running" : "disabled",
                 error: null,
                 capabilities: [...manifest.capabilities],
                 directory: `/test-host/packages/${manifest.id}`,

package/dist/plugin/types.d.ts

@@ -592,15 +592,33 @@ export interface Plugin extends Scope {
  * - `uninstall`: the user uninstalls it.
  * - `reload`: it is reloaded (from the plugin manager, or a development
  *   load with `--plugin`).
- * - `upgrade`: a new version replaces it.
- * - `idle`: lazy activation stops it after a while without use; its next
- *   use starts it again ([Idle plugins](../../docs/explanation/plugins.md#idle-plugins-are-stopped)).
- * - `failed`: the player stops it for a fault (planned to cover an
- *   unreadable or oversized line, a malformed request, an input queue that
- *   overflowed, an uncaught exception in the shared process).
+ * - `upgrade`: an install or update replaces the running version; also a
+ *   new version stopped because its install was cancelled (the previous
+ *   version comes back).
+ * - `idle`: lazy activation parks it; its next use starts it again
+ *   ([Idle plugins](../../docs/explanation/plugins.md#idle-plugins-are-stopped)).
+ *   Lazy activation is off by default (`VESTRA_LAZY=1` turns it on); when
+ *   on, it parks a plugin after a while without use, and parks one whose
+ *   first run it judges lazy right after it is ready.
+ * - `failed`: the player stops it for a fault it can still tell the plugin
+ *   about (planned to cover a malformed request, an unreadable or
+ *   oversized line, an activation timeout, an uncaught exception the
+ *   shared process attributes to this plugin).
  * - `host-lost`: the plugin's runner saw its pipe to the player close
  *   without a stop: the player crashed or was killed. Requests are refused
- *   with `disabled`; clean up locally only.
+ *   with `disabled`; clean up locally only. Player 0.6.4 sends `quit` on a
+ *   normal exit; read `host-lost` as "the player is gone", not as proof of
+ *   a crash.
+ *
+ * Some ends are no stop at all: the plugin gets no reason and its
+ * {@link Scope.onDispose} cleanups do not run. That is the case when its
+ * own process is killed because its input queue is full or a write to it
+ * failed, when its own process fails to activate (the runner exits without
+ * cleaning up), when the process has already exited, and when the shared
+ * runner is restarted as a whole (a hang, a fault it cannot attribute, an
+ * unreadable line of its own, a member's full input queue, the runner
+ * exiting): every member is killed with it. Keep state that must survive
+ * such an end in storage as it changes, not only in a cleanup.
  *
  * Planned for player 0.6.4: the player sends the reason with
  * `runtime.stop` and its runner reports `host-lost`; the exact list may
@@ -3122,7 +3140,13 @@ export interface Appearance {
      * Needs `events`: without it the listener never runs for other plugins'
      * changes. Views need no help to follow the palette; use this for things
      * the plugin draws itself (a rendered image, colours it computes). Errors
-     * go to {@link Scope.onError}.
+     * go to {@link Scope.onError}. When the player starts a stopped plugin
+     * for a palette change (player 0.5.21), {@link Appearance.theme} already
+     * has the new palette at start and the listener still hears the change
+     * (SDK 1.5.56; before, it did not run). A language change does not call
+     * it, except in one case: a plugin started for a language change alone
+     * may hear the unchanged palette once, since the player's event does not
+     * say which of the two changed.
      *
      * @capability events
      *
@@ -8406,6 +8430,10 @@ export interface Resolvers {
     /**
      * {@link Resolvers.fileTypes} changed: a file resolver was added, or its
      * plugin stopped. Needs `events`; without it the listener never fires.
+     * When the player starts a stopped plugin for this change (player
+     * 0.5.21), {@link Resolvers.fileTypes} already has the new list at start
+     * and the listener still hears the change (SDK 1.5.56; before, it did not
+     * run).
      *
      * @param listener - Receives the new list.
      * @returns A handle that removes the listener.
@@ -8516,6 +8544,27 @@ export interface InstallOptions {
      * reconnects to it.
      */
     replace?: boolean;
+    /**
+     * Whether the plugin runs once installed (SDK 1.5.55). Left out, a first
+     * install runs and an update or reinstall (from any source, `replace`
+     * included) keeps the installed plugin's state: one the user or a store
+     * disabled stays disabled, and only its files are installed (nothing
+     * starts it, so the change commits without an `activating` step). `true`
+     * enables and starts it, for example a version the store disabled that
+     * an update fixes; if it fails to start, the old version is restored,
+     * still disabled. `false` installs it disabled: a running version is
+     * stopped and its session values go, as with {@link Packages.setEnabled}.
+     * Built-in plugins always run (and cannot be installed over). A value
+     * that is not a boolean is `invalid`.
+     *
+     * Planned for player 0.6.4: older players ignore it and an install there
+     * always runs the plugin, so after a committed install call
+     * {@link Packages.setEnabled} when the state matters.
+     *
+     * @player 0.6.4 (planned); older players ignore it (an install always
+     *   enables the plugin).
+     */
+    enabled?: boolean;
 }
 /**
  * A validated package directory, from {@link Packages.validate}.
@@ -8560,9 +8609,14 @@ export interface PackageCandidate {
      * a built-in id fails with `unsupported` (built-ins update with the
      * player). A reserved id (`vestra` or `vestra.*`, which every built-in
      * uses) fails with `reserved` (player 0.4.1; already when validated), as
-     * only the player installs built-in plugins.
+     * only the player installs built-in plugins. An update keeps a disabled
+     * plugin disabled unless `enabled` says otherwise (planned for player
+     * 0.6.4; see {@link InstallOptions.enabled}).
      *
      * @capability plugins.manage
+     * @throws `invalid` (rejects) An option is malformed: a `source` the
+     *   player does not accept, or a `replace` or `enabled` that is not a
+     *   boolean.
      * @throws `conflict` (rejects) The plugin is installed from another source
      *   and `replace` is not set.
      * @throws `unsupported` (rejects) A built-in plugin's id.
@@ -8585,7 +8639,19 @@ export interface PackageCandidate {
      * declare const candidate: PackageCandidate;
      * // ---cut---
      * const change = await candidate.install({ replace: true });
-     * await change.done; // "committed" once the new plugin runs
+     * await change.done; // "committed" once installed (running unless it stays disabled)
+     * ```
+     *
+     * @example Enable a fixed version of a plugin the store disabled
+     * A store disabled a version it revoked; the update that fixes it
+     * should run again. Without `enabled` the update keeps the plugin
+     * disabled (player 0.6.4); `true` enables it once installed. Older
+     * players ignore the option and enable every install.
+     * ```ts
+     * declare const candidate: PackageCandidate;
+     * // ---cut---
+     * const change = await candidate.install({ enabled: true });
+     * await change.done; // "committed" once the fixed version runs
      * ```
      *
      * @since 1.0.0
@@ -9665,7 +9731,10 @@ export interface Storage {
  * | --- | --- |
  * | The plugin's process restarts: reload, upgrade, crash | kept |
  * | The plugin failed to start or failed, and starts again | kept |
- * | The user disables the plugin, or uninstalls it | cleared |
+ * | The user, or a plugin with `plugins.manage` (`packages.setEnabled(id, false)`), disables the plugin | cleared |
+ * | An update or reinstall with `enabled: false` switches an enabled plugin off (player 0.6.4) | cleared |
+ * | The plugin is uninstalled | cleared |
+ * | An earlier installation kept for a later reinstall (after a `replace`) is dropped because the player keeps only so many | cleared |
  * | The player quits | cleared |
  *
  * - **Per plugin.** A plugin sees only its own keys. Like

package/dist/wire.d.ts

@@ -731,10 +731,15 @@ export declare function createWire(transport: Transport): {
         /** Player 0.2.0: a `.vxp` file. */
         validateArchive: (file: string) => Promise<PackageValidation>;
         installed: (id: string) => Promise<InstalledPackage>;
-        /** `source` and `replace` are sent only when given (player 0.2.0). */
+        /**
+         * `source` and `replace` are sent only when given (player 0.2.0);
+         * `enabled` only when given (planned for player 0.6.4, older players
+         * ignore it).
+         */
         install: (token: string, expectedRevision: number, requestId: string, options?: {
             source?: WireSource;
             replace?: boolean;
+            enabled?: boolean;
         }) => Promise<PackageOperation>;
         operation: (operationId: string) => Promise<PackageOperation>;
         cancel: (operationId: string) => Promise<PackageOperation>;

package/dist/wire.js

@@ -341,13 +341,20 @@ export function createWire(transport) {
                 file,
             }),
             installed: (id) => transport.request("packages.installed", { id }),
-            /** `source` and `replace` are sent only when given (player 0.2.0). */
+            /**
+             * `source` and `replace` are sent only when given (player 0.2.0);
+             * `enabled` only when given (planned for player 0.6.4, older players
+             * ignore it).
+             */
             install: (token, expectedRevision, requestId, options = {}) => transport.request("packages.install", {
                 token,
                 expectedRevision,
                 requestId,
                 ...(options.source === undefined ? {} : { source: options.source }),
                 ...(options.replace ? { replace: true } : {}),
+                ...(options.enabled === undefined
+                    ? {}
+                    : { enabled: options.enabled }),
             }),
             operation: (operationId) => transport.request("packages.operation", {
                 operationId,

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.54: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
+> @vestra-player/sdk 1.5.57: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
 
 ## Read the documentation
 

package/package.json

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