@vestra-player/sdk 1.5.53 → 1.5.55

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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.
+
+- **Why the plugin stops** (API request of the Shader Upscaling author). A plugin can tell an orderly stop from a lost player: `plugin.stopReason` is set when the stop begins, and every `onDispose` cleanup receives a `DisposeInfo` (`{ stopping, reason }`); a cleanup without parameters works as before. `stopping` is `false` for a child scope the plugin's own code disposed. Planned for player 0.6.4 (not released yet): the player sends `quit`, `disable`, `uninstall`, `reload`, `upgrade`, `idle` or `failed` with `runtime.stop`, and its runner passes `host-lost` when its input closes (or its output breaks) without a `runtime.stop` (the player crashed or was killed; requests are refused, clean up locally only). The runner hands the reason to the SDK (`PluginInstance.dispose({ reason })` in `@vestra-player/sdk/runtime`; a reason the SDK does not know reads as `undefined`).
+- **Older players.** Players up to 0.6.3 give no reason for any stop, a lost player included. One whose own SDK is older than 1.5.54 (0.6.3 and earlier) calls the cleanup **without an argument** and has no `plugin.stopReason` (it reads `undefined`): the parameter is optional (`info?: DisposeInfo`), so read it as `info?.reason`.
+- **`previous-crash`** (player 0.6.3) is documented on `VideoShaders`, `RenderOptions` and in the `PluginError` table: after a run of the player that ended while plugin shaders were drawing (a crash, the process being ended, a lost GPU device), the player refuses every non-empty shader list, the render options' `shaders` included, with `previous-crash` and a message naming the plugins; one such end keeps them off for the next start, two within a day until the GPU, its driver or the player changes, or for 7 days. Clearing still works, the player shows one OSD line itself, and plugins should not set the list again while it is refused (the SDK does not retry a `failed` handle). The render options send every value set so far with each `set`, the refused `shaders` included: include `shaders: []` in the next `set` to go on without them.
+- **`TestHost`**: `previousCrash` (a message, default `null`) refuses non-empty `video.shaders` lists and render options `shaders` with `previous-crash` as the player does, after the files are checked and before the GPU check. `failVideoShaders(id, message, code?)` (`failed` by default, or `previous-crash`) and `failVideoRender("previous-crash", …)` are shortcuts that only set the handle's status: the real player refuses the request instead, which `previousCrash` plays. `startPlugin`'s `stop` still declares no parameter (`stop.length === 0`, `t.after(stop)`, `promise.then(stop)`) and takes an optional `{ reason }`; `disconnect()` stops the plugin as when the player is lost (`host-lost`; requests in flight and later ones are refused with `disabled`, as the runner does).
+- **`TestHost` cleanup never fails a test.** `close()` (and so `stop()`) retries removing its temporary directory (`maxRetries: 5`, 100 ms apart) and leaves it to the system when Windows still refuses (an intermittent `ENOTEMPTY` on Windows CI, plugin repository run 41351136515).
+- _Docs_: [The plugin model](docs/explanation/plugins.md#stopping), [Host and Node](docs/explanation/host-and-node.md#stopping-a-plugin), [Video and audio processing](docs/explanation/processing.md#shaders), [Test a plugin](docs/how-to/testing.md) and [Reference: testing](docs/reference/testing.md) describe them.
+
 ## 1.5.53
 
 **Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed.

package/dist/plugin/index.d.ts

@@ -19,7 +19,17 @@ export interface PluginInstance {
      * `RuntimeOptions.strictDeclarations` is set.
      */
     activated(): Promise<void>;
-    dispose(): Promise<void>;
+    /**
+     * Stop the plugin: dispose the root scope, then stop the runtime.
+     * `info.reason` (SDK 1.5.54) is why: the runner passes `runtime.stop`'s
+     * `data.reason` (planned for player 0.6.4), or `"host-lost"` when its input closed
+     * without a `runtime.stop`. It reaches `plugin.stopReason` and every
+     * `onDispose` cleanup; a reason the SDK does not know reads as
+     * `undefined`. A second call runs no cleanup again and keeps the first reason.
+     */
+    dispose(info?: {
+        reason?: unknown;
+    }): Promise<void>;
 }
 export declare function createPlugin(transport: Transport, manifest: PluginManifest, directory: string, dataDirectory?: string, 
 /** `plugin.app` (the runner passes the player's `VESTRA_APP_INFO`). */

package/dist/plugin/index.js

@@ -1,4 +1,4 @@
-import { failure, Runtime } from "./runtime.js";
+import { failure, Runtime, stopReason } from "./runtime.js";
 import { ScopeImpl } from "./scope.js";
 import { playerOf } from "./player.js";
 import { windowOf } from "./window.js";
@@ -27,7 +27,8 @@ options) {
     return {
         plugin: root,
         activated: () => runtime.activated(),
-        dispose: async () => {
+        dispose: async (info) => {
+            runtime.stopping ??= { reason: stopReason(info?.reason) };
             await root.dispose();
             runtime.stop();
         },

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

@@ -1,5 +1,5 @@
 import type { Json, LocalServices, Transport, Wire } from "../wire.ts";
-import type { App, Disposable, Locale, PluginError, SystemInfo } from "./types.ts";
+import type { App, Disposable, Locale, PluginError, StopReason, SystemInfo } from "./types.ts";
 /**
  * Why something listens, for the player's log line that says why a plugin
  * keeps running (`events.subscribe { why }`, player 0.5.21): computed
@@ -46,6 +46,8 @@ export interface RuntimeOptions {
      */
     strictDeclarations?: boolean;
 }
+/** A stop reason the runner passed on, if this SDK knows it. */
+export declare function stopReason(value: unknown): StopReason | undefined;
 export declare const same: (a: Json | undefined, b: Json | undefined) => boolean;
 /** One value in flight, only the newest waiting. Each push learns its fate. */
 export declare class Latest<T> {
@@ -73,6 +75,13 @@ export declare class Runtime {
     readonly views: Map<string, (callback: string, args: Json[]) => void>;
     readonly commands: Map<string, () => void>;
     readonly services: Map<string, unknown>;
+    /**
+     * Set when the player stops the plugin (`PluginInstance.dispose`), before
+     * the root scope is disposed: `DisposeInfo` and `plugin.stopReason`.
+     */
+    stopping: {
+        reason: StopReason | undefined;
+    } | undefined;
     /** `plugin.app`, from the start-up handshake; `system()` asks the player. */
     readonly app: App;
     /** `plugin.i18n.locale`, from the start-up handshake; English when unknown. */

package/dist/plugin/runtime.js

@@ -96,6 +96,23 @@ const DECLARATION_REFUSALS = new Set([
     "conflict",
     "limit",
 ]);
+/** The reasons `StopReason` names; anything else reads as `undefined`. */
+const STOP_REASONS = new Set([
+    "quit",
+    "disable",
+    "uninstall",
+    "reload",
+    "upgrade",
+    "idle",
+    "failed",
+    "host-lost",
+]);
+/** A stop reason the runner passed on, if this SDK knows it. */
+export function stopReason(value) {
+    return typeof value === "string" && STOP_REASONS.has(value)
+        ? value
+        : undefined;
+}
 export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /** One value in flight, only the newest waiting. Each push learns its fate. */
 export class Latest {
@@ -191,6 +208,11 @@ export class Runtime {
     views = new Map();
     commands = new Map();
     services = new Map();
+    /**
+     * Set when the player stops the plugin (`PluginInstance.dispose`), before
+     * the root scope is disposed: `DisposeInfo` and `plugin.stopReason`.
+     */
+    stopping;
     /** `plugin.app`, from the start-up handshake; `system()` asks the player. */
     app;
     /** `plugin.i18n.locale`, from the start-up handshake; English when unknown. */

package/dist/plugin/scope.d.ts

@@ -1,11 +1,12 @@
 import type { Change, Runtime } from "./runtime.ts";
-import type { Disposable, Plugin, PluginError, Scope } from "./types.ts";
+import type { Disposable, DisposeInfo, Plugin, PluginError, Scope, StopReason } from "./types.ts";
 export declare class ScopeImpl implements Plugin {
     #private;
     readonly runtime: Runtime;
     constructor(runtime: Runtime, parent?: ScopeImpl);
     get id(): string;
     get dataDirectory(): string;
+    get stopReason(): StopReason | undefined;
     get disposed(): boolean;
     readonly commands: import("./types.ts").Commands;
     readonly when: import("./types.ts").When;
@@ -49,7 +50,7 @@ export declare class ScopeImpl implements Plugin {
     add<T extends Disposable>(item: T): T;
     /** Handles call this when disposed directly, so the scope forgets them. */
     forget(item: Disposable): void;
-    onDispose(cleanup: () => void | Promise<void>): Disposable;
+    onDispose(cleanup: ((info?: DisposeInfo) => void | Promise<void>) | (() => void | Promise<void>)): Disposable;
     onError(listener: (error: PluginError) => void): Disposable;
     report(error: unknown): void;
     /** Invoke plugin code on its behalf: report failures, then refresh bindings. */

package/dist/plugin/scope.js

@@ -39,6 +39,9 @@ export class ScopeImpl {
             throw failure("unavailable", "the player provided no data directory");
         return directory;
     }
+    get stopReason() {
+        return this.runtime.stopping?.reason;
+    }
     get disposed() {
         return this.#disposed || (this.#parent?.disposed ?? false);
     }
@@ -102,7 +105,12 @@ export class ScopeImpl {
                     return;
                 done = true;
                 this.forget(item);
-                await cleanup();
+                const stopping = this.runtime.stopping;
+                await cleanup(Object.freeze(stopping
+                    ? stopping.reason === undefined
+                        ? { stopping: true }
+                        : { stopping: true, reason: stopping.reason }
+                    : { stopping: false }));
             },
         };
         return this.add(item);

package/dist/plugin/testing.d.ts

@@ -18,7 +18,7 @@ import type { SubtitleState } from "../subtitles.ts";
 import { VIDEO_PROCESSING_LIMITS } from "../processing.ts";
 import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingDecodingCause, UpscalingPlugin, UpscalingReason, UpscalingVideoSize, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
-import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
+import type { LanguagePreference, Locale, Plugin, StopReason, TemplateArgs, TextValue, ThemeId } from "./types.ts";
 import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
 /** Throw one of these from `host.handle(...)` to simulate a definite refusal. */
 export { HostError };
@@ -1351,6 +1351,10 @@ export declare class TestHost implements Transport {
      * or switches to software rendering (`unsupported`, which also sets
      * `videoRender.gpu` to false and `rendering.reason` to `window-fallback`
      * with `message`). Pushed only when this plugin is the owner.
+     * `previous-crash` (SDK 1.5.54) is a shortcut that only sets the handle's
+     * status and reaches `onError`: the real player never pushes it, it
+     * refuses the `set` request itself. To test that, set
+     * {@link TestHost.previousCrash}.
      *
      * @example Make a shader fail to compile
      * The plugin's render options report `failed`, as when mpv rejects a
@@ -1372,7 +1376,7 @@ export declare class TestHost implements Transport {
      * @capability None.
      * @since 1.0.0
      */
-    failVideoRender(code: "failed" | "unsupported", message: string): void;
+    failVideoRender(code: "failed" | "unsupported" | "previous-crash", message: string): void;
     /**
      * The shader channel (`plugin.video.shaders(id)`, SDK 1.5.39): the lists
      * the player holds for this plugin's handles by id (the real paths, after
@@ -1405,6 +1409,12 @@ export declare class TestHost implements Transport {
      * rendering (`unsupported`; use {@link TestHost.failVideoRender}, which
      * also tells the handles). Pushed only to a handle that holds shaders.
      *
+     * `code` (SDK 1.5.54, default `failed`) is the error code pushed.
+     * `previous-crash` is a shortcut that only sets the handle's status and
+     * reaches `onError`: the real player (0.6.3) never pushes it, it refuses
+     * the `set` request itself after an abnormal end. To test that, set
+     * {@link TestHost.previousCrash}.
+     *
      * @capability None.
      *
      * @example Make the plugin's shader fail to compile
@@ -1430,7 +1440,37 @@ export declare class TestHost implements Transport {
      *
      * @since 1.5.39
      */
-    failVideoShaders(id: string, message: string): void;
+    failVideoShaders(id: string, message: string, code?: "failed" | "previous-crash"): void;
+    /**
+     * Play a run after an abnormal end with plugin shaders on (player 0.6.3):
+     * while set, a non-empty `video.shaders` list and a render options
+     * `set` with a non-empty `shaders` list are refused with
+     * `previous-crash` and this message; clearing still works. `null`
+     * (default): shaders apply.
+     *
+     * @example Check that the plugin stops retrying while shaders are off
+     * The plugin's shader handle turns `failed` with `previous-crash`, as
+     * in the player after a crash while plugin shaders were drawing. The
+     * player refuses the list itself (and shows its own OSD line), so the
+     * plugin should report it once and not set the list again.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { join } from "node:path";
+     * import { writeFileSync } from "node:fs";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.previousCrash = "plugin shaders are off for this start";
+     * const file = join(plugin.dataDirectory, "sharpen.glsl");
+     * writeFileSync(file, "//!HOOK MAIN\n");
+     * const shaders = plugin.video.shaders("sharpen");
+     * shaders.set([file]); // refused: the previous run ended abnormally
+     * await host.settle();
+     * assert.equal(shaders.status.state, "failed");
+     * ```
+     *
+     * @since 1.5.54
+     */
+    previousCrash: string | null;
     /**
      * The player's processing (filter) state. Wire-level; may change in minor
      * versions. `resources` holds each `video.filter` / `audio.filter` chain the
@@ -1942,6 +1982,11 @@ export declare class TestHost implements Transport {
         /** Start time in seconds. */
         start: number;
     }[];
+    /**
+     * @internal `startPlugin`'s `disconnect()`: refuse every request, the
+     * ones in flight included, as the runner does once the player is gone.
+     */
+    loseConnection(): void;
     /**
      * `plugin.dataDirectory`: a fresh empty temporary directory, removed with
      * the host on `stop()`. `plugin.storage.json` reads and writes real files
@@ -2391,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;
@@ -2405,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`
@@ -2422,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
@@ -2754,7 +2831,11 @@ export declare class TestHost implements Transport {
  * @returns `host`: the {@link TestHost}; `plugin`: the object passed to
  *   `activate` (call the plugin API on it directly); `stop()`: dispose the
  *   plugin like the player stopping it (scopes released, stores flushed),
- *   wait until the host is idle and remove the host's temporary files.
+ *   wait until the host is idle and remove the host's temporary files;
+ *   `stop({ reason })` (SDK 1.5.54): `reason` is the `StopReason` the player
+ *   sends; `disconnect()` (SDK 1.5.54) stops it as when the player is lost
+ *   (`host-lost`, requests refused with `disabled`). Removing the
+ *   temporary files never fails a test.
  *
  * @example Test that a setting survives a restart
  * The test turns on the 10-step option, stops the plugin, starts it again
@@ -2843,6 +2924,25 @@ export declare function startPlugin(activate: (plugin: Plugin) => unknown, optio
     host: TestHost;
     /** The `plugin` object passed to `activate`. */
     plugin: Plugin;
-    /** Stop the plugin, wait for the host, and remove temporary files. */
-    stop(): Promise<void>;
+    /**
+     * Stop the plugin, wait for the host, and remove temporary files.
+     * `stop({ reason })` (SDK 1.5.54): `reason` is the reason the player
+     * gives (`plugin.stopReason`, the `onDispose` cleanups'
+     * `info.reason`); `stop()`: none (`undefined`), as with players up to
+     * 0.6.3. It still takes no declared parameter, so it can be passed as
+     * a callback (`t.after(stop)`, `promise.then(stop)`).
+     */
+    stop: {
+        (): Promise<void>;
+        (options: {
+            reason?: StopReason;
+        }): Promise<void>;
+    };
+    /**
+     * Lose the player (SDK 1.5.54): as when it crashes or is killed, the
+     * runner stops the plugin with reason `host-lost`; requests still
+     * waiting for their answer and every later request are refused with
+     * `disabled`. Then waits and removes the temporary files like `stop`.
+     */
+    disconnect(): Promise<void>;
 }>;

package/dist/plugin/testing.js

@@ -1510,6 +1510,10 @@ export class TestHost {
      * or switches to software rendering (`unsupported`, which also sets
      * `videoRender.gpu` to false and `rendering.reason` to `window-fallback`
      * with `message`). Pushed only when this plugin is the owner.
+     * `previous-crash` (SDK 1.5.54) is a shortcut that only sets the handle's
+     * status and reaches `onError`: the real player never pushes it, it
+     * refuses the `set` request itself. To test that, set
+     * {@link TestHost.previousCrash}.
      *
      * @example Make a shader fail to compile
      * The plugin's render options report `failed`, as when mpv rejects a
@@ -1581,6 +1585,12 @@ export class TestHost {
      * rendering (`unsupported`; use {@link TestHost.failVideoRender}, which
      * also tells the handles). Pushed only to a handle that holds shaders.
      *
+     * `code` (SDK 1.5.54, default `failed`) is the error code pushed.
+     * `previous-crash` is a shortcut that only sets the handle's status and
+     * reaches `onError`: the real player (0.6.3) never pushes it, it refuses
+     * the `set` request itself after an abnormal end. To test that, set
+     * {@link TestHost.previousCrash}.
+     *
      * @capability None.
      *
      * @example Make the plugin's shader fail to compile
@@ -1606,14 +1616,44 @@ export class TestHost {
      *
      * @since 1.5.39
      */
-    failVideoShaders(id, message) {
+    failVideoShaders(id, message, code = "failed") {
         if ((this.videoShaders.handles.get(id)?.length ?? 0) > 0)
             this.emit("video.shaders.status", {
                 id,
                 state: "failed",
-                error: { code: "failed", message },
+                error: { code, message },
             });
     }
+    /**
+     * Play a run after an abnormal end with plugin shaders on (player 0.6.3):
+     * while set, a non-empty `video.shaders` list and a render options
+     * `set` with a non-empty `shaders` list are refused with
+     * `previous-crash` and this message; clearing still works. `null`
+     * (default): shaders apply.
+     *
+     * @example Check that the plugin stops retrying while shaders are off
+     * The plugin's shader handle turns `failed` with `previous-crash`, as
+     * in the player after a crash while plugin shaders were drawing. The
+     * player refuses the list itself (and shows its own OSD line), so the
+     * plugin should report it once and not set the list again.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { join } from "node:path";
+     * import { writeFileSync } from "node:fs";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.previousCrash = "plugin shaders are off for this start";
+     * const file = join(plugin.dataDirectory, "sharpen.glsl");
+     * writeFileSync(file, "//!HOOK MAIN\n");
+     * const shaders = plugin.video.shaders("sharpen");
+     * shaders.set([file]); // refused: the previous run ended abnormally
+     * await host.settle();
+     * assert.equal(shaders.status.state, "failed");
+     * ```
+     *
+     * @since 1.5.54
+     */
+    previousCrash = null;
     /**
      * The player's processing (filter) state. Wire-level; may change in minor
      * versions. `resources` holds each `video.filter` / `audio.filter` chain the
@@ -2099,6 +2139,25 @@ export class TestHost {
     #overrides = new Map();
     #listeners = new Map();
     #inFlight = 0;
+    /** `disconnect()` of `startPlugin`: the player is gone. */
+    #lost = false;
+    #lose = () => { };
+    /** Rejects when the player is lost: requests in flight fail with it. */
+    #gone = (() => {
+        const gone = new Promise((_, reject) => {
+            this.#lose = reject;
+        });
+        gone.catch(() => { });
+        return gone;
+    })();
+    /**
+     * @internal `startPlugin`'s `disconnect()`: refuse every request, the
+     * ones in flight included, as the runner does once the player is gone.
+     */
+    loseConnection() {
+        this.#lost = true;
+        this.#lose(new HostError("disabled", "plugin stopped"));
+    }
     #next = { snapshot: 0, job: 0, producer: 0, source: 0, resolution: 0 };
     #sourceBook = new Map();
     /** The pending resolutions' stamps and operations (beside `resolutions`). */
@@ -2573,6 +2632,10 @@ export class TestHost {
      * override from {@link TestHost.handle} or the default behaviour.
      */
     async request(method, params = {}) {
+        // After `disconnect()`: refused as the runner refuses them once the
+        // player is gone.
+        if (this.#lost)
+            throw new HostError("disabled", "plugin is stopping");
         const record = (params ?? {});
         // The plugin runner refuses a request over the message limit before
         // sending it (runtime/runner.ts): the player never sees it.
@@ -2583,10 +2646,15 @@ export class TestHost {
         this.#inFlight++;
         try {
             await tick();
+            if (this.#lost)
+                throw new HostError("disabled", "plugin stopped");
             const handler = this.#overrides.get(method) ?? this.#defaults[method];
             if (!handler)
                 throw new HostError("unsupported", `test host has no ${method}`);
-            return (await handler(record));
+            const work = Promise.resolve(handler(record));
+            // `disconnect()` fails the requests still waiting, as the runner does.
+            work.catch(() => { });
+            return (await Promise.race([work, this.#gone]));
         }
         finally {
             this.#inFlight--;
@@ -3031,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`
@@ -3048,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
@@ -3424,7 +3524,20 @@ export class TestHost {
     close() {
         for (const producer of this.producers.values())
             producer.server.close();
-        rmSync(this.#scratch, { recursive: true, force: true });
+        // Cleanup never fails a test: on Windows a file a closing handle still
+        // holds makes the removal fail now and then (`ENOTEMPTY`, `EBUSY`,
+        // `EPERM`); retry, then leave the directory to the system's cleanup.
+        try {
+            rmSync(this.#scratch, {
+                recursive: true,
+                force: true,
+                maxRetries: 5,
+                retryDelay: 100,
+            });
+        }
+        catch {
+            // Left in the temporary directory.
+        }
     }
     // ------------------------------------------------------------ simulated host
     #intent(intent) {
@@ -4575,6 +4688,12 @@ export class TestHost {
             return null;
         },
         "video.render.set": (p) => {
+            // The player's crash guard comes first (`processing_video.rs`).
+            const listed = p.values?.shaders;
+            if (this.previousCrash !== null &&
+                Array.isArray(listed) &&
+                listed.length > 0)
+                throw new HostError("previous-crash", this.previousCrash);
             if (!this.videoRender.gpu)
                 throw new HostError("unsupported", "render options need GPU rendering; the player renders in software");
             const owner = this.videoRender.owner;
@@ -4610,6 +4729,9 @@ export class TestHost {
             if (listProblem?.startsWith("at most"))
                 throw new HostError("limit", listProblem);
             const paths = list.map((path) => ownFile(path, this.fileRoots, "shader", VIDEO_PROCESSING_LIMITS.shaderBytes));
+            // The player's crash guard, after the files are checked.
+            if (paths.length > 0 && this.previousCrash !== null)
+                throw new HostError("previous-crash", this.previousCrash);
             if (paths.length > 0 && !this.videoRender.gpu)
                 throw new HostError("unsupported", "shaders need GPU rendering; the player renders in software");
             const mine = [...this.videoShaders.handles]
@@ -5015,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");
@@ -5030,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}`,
@@ -5455,7 +5588,11 @@ function tellResidency(host) {
  * @returns `host`: the {@link TestHost}; `plugin`: the object passed to
  *   `activate` (call the plugin API on it directly); `stop()`: dispose the
  *   plugin like the player stopping it (scopes released, stores flushed),
- *   wait until the host is idle and remove the host's temporary files.
+ *   wait until the host is idle and remove the host's temporary files;
+ *   `stop({ reason })` (SDK 1.5.54): `reason` is the `StopReason` the player
+ *   sends; `disconnect()` (SDK 1.5.54) stops it as when the player is lost
+ *   (`host-lost`, requests refused with `disabled`). Removing the
+ *   temporary files never fails a test.
  *
  * @example Test that a setting survives a restart
  * The test turns on the 10-step option, stops the plugin, starts it again
@@ -5552,14 +5689,43 @@ export async function startPlugin(activate, options = {}) {
     }
     await host.settle();
     tellResidency(host);
+    // Zero declared parameters (`stop.length === 0`) and a `()` overload, so
+    // `t.after(stop)`, `promise.then(stop)` and done-callback test runners
+    // see the same function as before 1.5.54.
+    const stop = async (...args) => {
+        // Only an object with `reason` counts (a value `then` or a test
+        // runner passes is ignored; an unknown reason reads as none).
+        const first = args[0];
+        const reason = typeof first === "object" && first !== null && "reason" in first
+            ? first.reason
+            : undefined;
+        await instance.dispose({ reason });
+        await host.settle();
+        host.close();
+    };
     return {
         /** The test host the plugin talks to. */
         host,
         /** The `plugin` object passed to `activate`. */
         plugin: instance.plugin,
-        /** Stop the plugin, wait for the host, and remove temporary files. */
-        async stop() {
-            await instance.dispose();
+        /**
+         * Stop the plugin, wait for the host, and remove temporary files.
+         * `stop({ reason })` (SDK 1.5.54): `reason` is the reason the player
+         * gives (`plugin.stopReason`, the `onDispose` cleanups'
+         * `info.reason`); `stop()`: none (`undefined`), as with players up to
+         * 0.6.3. It still takes no declared parameter, so it can be passed as
+         * a callback (`t.after(stop)`, `promise.then(stop)`).
+         */
+        stop,
+        /**
+         * Lose the player (SDK 1.5.54): as when it crashes or is killed, the
+         * runner stops the plugin with reason `host-lost`; requests still
+         * waiting for their answer and every later request are refused with
+         * `disabled`. Then waits and removes the temporary files like `stop`.
+         */
+        async disconnect() {
+            host.loseConnection();
+            await instance.dispose({ reason: "host-lost" });
             await host.settle();
             host.close();
         },

package/dist/plugin/types.d.ts

@@ -123,6 +123,7 @@ export interface Disposable {
  * | `resolution` | A file or web resolver's result could not be opened; `message` has the reason. |
  * | `revisionConflict` | {@link Packages}: the installed revision changed since it was read (another install or uninstall ran). Read again and retry; the SDK passes the revision it read, so this reaches plugins that act on old data. |
  * | `source-geometry`, `source-geometry-unsupported` | The source's picture size or rotation could not be applied: invalid decoder dimensions / a rotation that is not a multiple of 90°. |
+ * | `previous-crash` | {@link VideoShaders}, {@link RenderOptions} `shaders` (player 0.6.3): plugin shaders are off because the player ended abnormally while they were drawing; clearing still works. Do not retry while refused (the player shows its own OSD line). |
  * | `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. |
  *
@@ -416,10 +417,36 @@ export interface Scope extends Disposable {
      * plugin.onDispose(() => clearInterval(timer));
      * ```
      *
+     * @example Save a cache at once when the player is lost
+     * The plugin writes its cache file at once when the player crashed or
+     * was killed, instead of waiting for the next periodic save. The cleanup
+     * may get a {@link DisposeInfo}: `stopping` says the plugin itself stops
+     * (not a child scope), `reason` why (planned for player 0.6.4). Players
+     * whose SDK is older than 1.5.54 call the cleanup without an argument,
+     * so read it with `?.`.
+     * ```ts
+     * declare function saveCacheNow(): void;
+     * // ---cut---
+     * plugin.onDispose((info) => {
+     *   // The player is gone: ask it nothing, keep what is local.
+     *   if (info?.reason === "host-lost") saveCacheNow();
+     * });
+     * ```
+     *
+     * @remarks
+     * From SDK 1.5.54 in the player (and in `TestHost`) the cleanup is called
+     * with one argument, a {@link DisposeInfo}: whether the plugin stops, and
+     * why. A player whose own SDK is older calls it without one (`info` is
+     * `undefined`). A cleanup that takes no argument works as before; a
+     * function with optional parameters of its own that is passed directly
+     * (`onDispose(controller.abort.bind(controller))`) now receives the
+     * `DisposeInfo` as its first argument: wrap it (`() => controller.abort()`)
+     * when that matters.
+     *
      * @capability None.
      * @since 1.0.0
      */
-    onDispose(cleanup: () => void | Promise<void>): Disposable;
+    onDispose(cleanup: ((info?: DisposeInfo) => void | Promise<void>) | (() => void | Promise<void>)): Disposable;
     /**
      * Errors thrown by handlers that the SDK invoked (command `run`, window and
      * panel callbacks, `onChange` listeners) in this scope. Without a listener
@@ -547,6 +574,83 @@ export interface Plugin extends Scope {
      * none. See [How a plugin runs](../../docs/explanation/plugins.md#the-data-directory).
      */
     readonly dataDirectory: string;
+    /**
+     * Why the player stops this plugin (SDK 1.5.54; the reasons are planned
+     * for player 0.6.4): set when the stop begins, before any
+     * {@link Scope.onDispose} cleanup runs. `undefined` while the plugin
+     * runs, and for every stop by an older player (one whose own SDK is older
+     * than 1.5.54 does not have the property at all). See {@link StopReason}.
+     */
+    readonly stopReason: StopReason | undefined;
+}
+/**
+ * Why the player stopped the plugin ({@link DisposeInfo.reason},
+ * {@link Plugin.stopReason}).
+ *
+ * - `quit`: the player quits.
+ * - `disable`: the user disabled the plugin.
+ * - `uninstall`: the user uninstalls it.
+ * - `reload`: it is reloaded (from the plugin manager, or a development
+ *   load with `--plugin`).
+ * - `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. 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
+ * still change with that release. Players up to 0.6.3 give no reason for
+ * any stop, a lost player included (`undefined`); so does a stop that
+ * does not come from the player (a `TestHost` `stop()` without a reason).
+ * A value this SDK does not know reads as `undefined`.
+ *
+ * @player 0.6.4 (planned); older players give no reason (`undefined`).
+ * @since 1.5.54
+ * @category Plugin
+ */
+export type StopReason = "quit" | "disable" | "uninstall" | "reload" | "upgrade" | "idle" | "failed" | "host-lost";
+/**
+ * What a {@link Scope.onDispose} cleanup is told (SDK 1.5.54). A player
+ * whose own SDK is older passes nothing, so the cleanup's parameter is
+ * optional.
+ *
+ * @since 1.5.54
+ * @category Plugin
+ */
+export interface DisposeInfo {
+    /**
+     * `true` when the plugin itself stops (the player stops it), `false`
+     * when the plugin's own code disposed this scope or one of its parents.
+     */
+    readonly stopping: boolean;
+    /**
+     * Why the player stops the plugin (planned for player 0.6.4); `undefined` while
+     * `stopping` is false, and for every stop by an older player.
+     */
+    readonly reason?: StopReason;
 }
 /**
  * The state of a command's menu item, as the player shows it.
@@ -6716,7 +6820,13 @@ export interface RenderSettings {
  * the player's first answer to `render()` (reported to `onError` too), and so is
  * every `set`. Single owner, like {@link VideoView}. `set` never throws; the
  * result shows in `status`. For shaders that several plugins add at the
- * same time, use {@link VideoShaders} (SDK 1.5.39).
+ * same time, use {@link VideoShaders} (SDK 1.5.39). After a run of the
+ * player that ended abnormally while plugin shaders were drawing, a `set`
+ * whose merged values hold a non-empty `shaders` list is refused with
+ * `previous-crash` (player 0.6.3; the rules are on {@link VideoShaders}).
+ * Every `set` sends all the values set so far, the refused `shaders`
+ * included, so include `shaders: []` in the next `set` to go on without
+ * them.
  *
  * @capability processing.video, playback.read and events (like
  * {@link VideoFilter})
@@ -6745,7 +6855,15 @@ export interface RenderOptions extends Disposable {
      * `failed` with `unsupported` while the player renders in software;
      * `failed` with `failed` when mpv cannot compile a shader (pushed later;
      * while other plugins' {@link VideoShaders} are on too, the player
-     * cannot tell whose shader failed and says so in the message).
+     * cannot tell whose shader failed and says so in the message);
+     * `failed` with `previous-crash` (player 0.6.3) when a `set` with a
+     * non-empty `shaders` list comes after a run of the player that ended
+     * abnormally while plugin shaders were drawing (the rules are the same
+     * as for {@link VideoShaders}). The handle keeps the refused list among
+     * its values and every `set` sends them all, so a later `set` without
+     * `shaders` is refused again: include `shaders: []` in it
+     * (`set({ shaders: [], toneMapping: "bt.2390" })`); `dispose` always
+     * works.
      */
     readonly status: FilterStatus;
     /**
@@ -6805,6 +6923,20 @@ export interface RenderOptions extends Disposable {
  * Players before 0.5.20 refuse the request (the handle is `failed`): declare
  * `"minPlayerVersion": "0.5.20"`.
  *
+ * **After an abnormal end** (player 0.6.3): when the previous run of the
+ * player ended while plugin shaders were drawing (a crash, the process
+ * being ended, a lost GPU device), the player refuses every non-empty
+ * list of every plugin with `previous-crash`, its message naming the
+ * plugins whose shaders were on: one such end keeps them off for the next
+ * start only; two within a day keep them off until the GPU, its driver or
+ * the player changes, or for 7 days. Clearing (`[]`, `clear`,
+ * `dispose`) still works. The player shows one OSD line about it itself;
+ * the handle is `failed` with `previous-crash` and the SDK does not
+ * retry it. Do not set the list again in a loop while it is refused, and
+ * do not show an OSD line of your own for it; a later start of the player
+ * applies lists again once the guard lets it. Players before 0.6.3 never
+ * refuse with it.
+ *
  * @example Add a sharpening shader the plugin ships
  * The video looks sharper on the GPU renderer; under software rendering
  * the OSD says why it is not. The shader file lives in the plugin's
@@ -6835,7 +6967,8 @@ export interface VideoShaders extends Disposable {
      *
      * @remarks
      * Never throws: a refused list shows in `status` (`invalid`, `missing`,
-     * `limit`, `unsupported`) and goes to {@link Scope.onError}, and what the
+     * `limit`, `unsupported`, and `previous-crash` from player 0.6.3: see
+     * the interface's remarks) and goes to {@link Scope.onError}, and what the
      * player held stays.
      *
      * @capability processing.video
@@ -8401,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}.
@@ -8445,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.
@@ -8470,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.53: 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
 
@@ -32,7 +32,7 @@
 - `/API/Media`: 6 entries: CaptureOptions, Snapshot, ExportOptions, JobState, ExportJob, MediaCapture
 - `/API/Packages`: 10 entries: PackageManifest, PackageSource, InstallOptions, PackageCandidate, PackageChangeStatus, PackageChange, PluginInfo, PluginDisplay, PluginWarning, Packages
 - `/API/Playback`: 18 entries: MarkKind, TimelineMark, TimelineLayer, Timeline, AudioTrack, PlayerState, AudioDevice, Chapter, Conditional, Media, Scrub, StreamFrame, StreamOptions, StreamStartError, Stream,…
-- `/API/Plugin`: 11 entries: Disposable, PluginError, Scope, Plugin, WindowState, MainWindow, AppInfo, App, SystemInfo, DisplayInfo, Json
+- `/API/Plugin`: 13 entries: Disposable, PluginError, Scope, Plugin, StopReason, DisposeInfo, WindowState, MainWindow, AppInfo, App, SystemInfo, DisplayInfo, Json
 - `/API/Processing`: 18 entries: FilterStatus, VideoFilter, AudioFilter, ViewSettings, VideoView, RenderSettings, RenderOptions, VideoShaders, UpscalingReasonCode, UpscalingReason, UpscalingDecodingCause,…
 - `/API/Services`: 15 entries: Clipboard, Power, ToolResult, Tools, JsonStore, Storage, SessionStorage, System, Secrets, RenderingMode, RenderingPreference, RenderingReasonCode, RenderingReason, RenderingState,…
 - `/API/Sources`: 7 entries: ResolverOptions, WebResolverOptions, FileResolverOptions, ResolvedStream, Resolver, Resolvers, ResolvedMedia

package/package.json

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