@vestra-player/sdk 1.5.54 → 1.5.55

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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/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/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
@@ -8516,6 +8534,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 +8599,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 +8629,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

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.55: 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.55",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {