@vestra-player/sdk 1.5.52 → 1.5.54

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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.
+
+- **`BUILTIN_COMMANDS`** lists the Info plugin's (`vestra.info` 0.1.11, player 0.6.3) top-level **Check for Updates…** (`info.update`, no default key), right after About Vestra Player… (the player's agreement test failed on it). The built-in command table in [Reference: commands](docs/reference/commands.md) follows.
+
 ## 1.5.52
 
 **Who must change: nobody.** Additive: `WindowState` gains `maximized`, `apiVersion` stays `vestra/1`, no new capability. Players before 0.6.3 do not report it and it reads `false` there; a plugin that depends on it sets `"minPlayerVersion": "0.6.3"`. A test that deep-compares the whole `plugin.window.state` now also sees `maximized: false`.

package/dist/commands.js

@@ -589,6 +589,7 @@ vestra.audio | audio.sync.reset | Reset ▸ Audio Sync | ?
 vestra.audio | audio.reset | Reset ▸ Audio Processing
 vestra.visualizer | reset-logo | Reset ▸ Idle Logo
 vestra.info | info.about | About Vestra Player… | F1
+vestra.info | info.update | Check for Updates…
 host | quit | Quit | Cmd+Q
 host | enter-fullscreen | (Enter Fullscreen)
 host | exit-fullscreen | (Leave Fullscreen)

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/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
@@ -2754,7 +2799,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 +2892,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--;
@@ -3424,7 +3492,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 +4656,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 +4697,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]
@@ -5455,7 +5545,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 +5646,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,65 @@ 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`: 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).
+ * - `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.
+ *
+ * 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 +6802,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 +6837,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 +6905,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 +6949,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

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.52: 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.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/.
 
 ## 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.52",
+  "version": "1.5.54",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {