@vestra-player/sdk 1.5.38 → 1.5.40

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.5.40
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. `plugin.when` needs player 0.5.21 (`"minPlayerVersion": "0.5.21"`); older players have no `plugin.when`. A plugin that does not use it sees no difference. What changes with the player's lazy activation (off by default; `VESTRA_LAZY=1`): a listener of `packages.changed`, `bindings.changed`, `appearance.changed` or `resolvers.fileTypes` no longer keeps a plugin running; the player stops it while idle and starts it again to deliver the event. `bindings.changed` (`plugin.bindings.onChange`) now fires only when the binding list changes, no longer when a plugin starts again with the same commands; nobody must change (the event carries no data, and the list is what it stands for).
+
+- **`plugin.when`** (player 0.5.21): conditions on the player's own state for a command's `enabled` and `checked`, evaluated by the player, so a stopped plugin's menu items still follow playback. The vocabulary: `open`, `ready`, `playing`, `paused`, `stream`, `fullscreen`, `phase(...phases)`, `can(control)` (the names of `PlayerState.can`), `theme(id)`, `language(preference)`; combine with `and`, `or`, `not()`. `enabled: when.playing`, `checked: when.theme("vestra-light")`. With an `enabled` condition the player shows the command's `reason` only while the condition is false (or the command is busy), so a fixed reason is enough. A condition reads nothing in the plugin and keeps no listener; a function (`enabled: () => plugin.player.state.phase === "ready"`) keeps working and keeps the plugin running, as before. Wire form: `commands.register` and `commands.update` carry `when: { enabled?, checked? }` (one-key condition objects: `phase`, `paused`, `kind`, `can`, `fullscreen`, `theme`, `language`, `all`, `any`, `not`); the state fields they cover carry a placeholder. New types `When`, `Condition`; `Command.set` and `CommandOptions.enabled`/`checked` accept a condition.
+- **Why a plugin keeps running.** The SDK tells the player everything that listens to an event and where the plugin added it (`events.subscribe { event, why: [...] }`, player 0.5.21 logs it; older players ignore it): `a listener added at main.ts:570`, `command "Snapshot" enabled is a function that reads plugin.player.state (main.ts:353) — use plugin.when`. The player's log names it when it keeps a plugin running, and for a development load (`--plugin`) at its start.
+- **`TestHost`**: evaluates conditions as the player does (`FakeCommand.state` against `source`, `mainWindow.fullscreen`, `appearance` and `language`; `FakeCommand.when` is what was sent); `listeningWhy` (every reason each event of `listening` is listened to); `plugin.when.theme` and `language` refuse ids the player does not have (`TypeError`); `keepsRunning` (why the player would keep the plugin running: listeners of events other than the four above, a mounted panel, open windows). `vestra-plugin test` prints `keepsRunning` once per test file when it is not empty.
+
+## 1.5.39
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`, no new capability. The new API needs player 0.5.20 (`"minPlayerVersion": "0.5.20"`): older players refuse the new node kinds with `invalid` and the shader request as unknown, which shows as a `failed` handle. A plugin that uses none of it sees no difference; `plugin.video.render()` (its `shaders` included) behaves as before.
+
+- **Shader channel `plugin.video.shaders(id?)`** (player 0.5.20, `processing.video`): this plugin's own mpv user shaders, with any number of plugins holding handles at the same time (`render()` keeps its single owner). `set(paths)` sends the handle's whole list (last write wins), `clear()` and `dispose()` withdraw it, `status`/`onStatus` as for filters. The player joins every list after the render options' own `shaders`, in a stable order: built-in plugins, then installed plugins in the order they were first installed, then development loads; ties by plugin id, a plugin's handles by id. At most 16 shaders across all handles (`limit`; the render options keep their own 16). Files must be the plugin's own (package or data directory after following links, at most 16 MiB; `invalid` elsewhere, `missing` when absent). GPU rendering only (`unsupported` under software rendering; when the player switches to software during the run every handle hears `unsupported` and its list is removed, to be set again once the player draws on the GPU); never in snapshots or exports. A compile failure is pushed to every handle with shaders not yet told; whenever more than one holder has shaders on (other handles or `render().shaders`), the message says the player cannot tell whose shader failed. Handle ids, like `lut3d` paths, refuse C0 and C1 control characters. New type `VideoShaders`.
+- **`convolution` and `lut3d` video nodes** (player 0.5.20): `{ kind: "convolution", planes }` takes one integer kernel per plane (`ConvolutionPlane`: `mode` `square` with 9, 25 or 49 entries, or `row`/`column` with an odd count up to 49; `rdiv`, `bias`), strictly checked; `{ kind: "lut3d", file, interpolation }` recolours with a `.cube` file from the plugin's package or data directory (`LUT_3D_SIZE` 2–65, 16 MiB, no `[` or `]` in the path). Both run in the filter chain like the other nodes, so they apply to processed snapshots and exports, and they need frames in memory (copy-back decoding). New type `ConvolutionPlane`.
+- **`VIDEO_PROCESSING_LIMITS`** (`@vestra-player/sdk/testing`): the bounds above (including `lutPathBytes`, 4096), in the generated table of _Limits_.
+- **`TestHost`**: `videoShaders` (this plugin's lists by id, `others` for other plugins' count), `fileRoots` (the package and data directory `startPlugin` sets), `failVideoShaders(id, message)`; `failVideoRender("unsupported")` also tells the shader handles and removes their lists; `processing.replace` checks `lut3d` files like the player.
+- Corrected: the reference no longer says only macOS renders on the GPU. Windows has GPU rendering since player 0.5.14 (Video ▸ GPU Rendering (Experimental), off by default): `RenderOptions`, `SystemInfo.rendering`, `PlaybackStats.backend`, `RenderingReasonCode` (`default`, `no-gpu-backend`) and the `TestHost.rendering` example say so.
+
 ## 1.5.38
 
 **Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The marks below are read by player 0.5.18 and later; older players ignore them, and a plugin built with an older SDK keeps working (the player builds the `plugin` object with its own SDK). What may change for a plugin is the player's lazy activation, off by default in player 0.5.18 and turned on in a later release: a plugin that holds nothing only its process can serve is stopped while idle and started on its next use, so state kept only in variables is lost between uses (keep it in `plugin.storage.session`).

package/bin/vestra-plugin.mjs

@@ -787,7 +787,11 @@ async function test(target) {
     run(
       process.execPath,
       ["--test", ...tests.map((file) => join(directory, file))],
-      { cwd: target.directory },
+      // startPlugin says why a plugin would keep running while idle.
+      {
+        cwd: target.directory,
+        env: { ...process.env, VESTRA_PLUGIN_RESIDENCY: "1" },
+      },
     ) !== 0
   )
     fail(`${target.name}: tests failed`);

package/dist/api-requests.js

@@ -118,6 +118,7 @@ export const API_REQUESTS = Object.freeze({
     ],
     "Plugin.video.view": [{ method: "video.view.set" }],
     "Plugin.video.render": [{ method: "video.render.set" }],
+    "Plugin.video.shaders": [{ method: "video.shaders.set" }],
     "Plugin.audio.filter": [
         { method: "processing.replace", params: { stage: "audio" } },
     ],

package/dist/commands.d.ts

@@ -1,6 +1,7 @@
 /** Finite candidate command registry. Host authenticates owner; no plugin supplies an owner id. */
 import type { Json, Transport } from "./wire.ts";
 import type { ListJson, TextJson } from "./i18n.ts";
+import type { ConditionJson } from "./plugin/when.ts";
 /**
  * The player's command registry caps, the same values as the player's own
  * table (the player's tests check that they agree). They are runaway guards,
@@ -238,6 +239,15 @@ export type CommandState = {
     /** Source text, or a text value (player 0.4.3). */
     reason: string | TextJson | ListJson | null;
 };
+/**
+ * A command's conditions (SDK 1.5.40, player 0.5.21): `enabled` and
+ * `checked` evaluated by the player (`plugin.when`). Older players ignore
+ * the field and show the state as sent.
+ */
+export type CommandWhen = {
+    enabled?: ConditionJson;
+    checked?: ConditionJson;
+};
 export type CommandDeclaration = {
     /** Source text, or a text value (player 0.4.3). */
     title: string | TextJson;
@@ -266,12 +276,12 @@ export type CommandDeclaration = {
     };
 };
 export declare function commandClient(transport: Transport): {
-    register: (id: string, revision: number, declaration: CommandDeclaration, state: CommandState) => Promise<{
+    register: (id: string, revision: number, declaration: CommandDeclaration, state: CommandState, when?: CommandWhen) => Promise<{
         revision: number;
     }>;
     /** Remove the command from the menu and the binding table; the id is free again. */
     unregister: (id: string) => Promise<void>;
-    update: (id: string, revision: number, state: CommandState) => Promise<{
+    update: (id: string, revision: number, state: CommandState, when?: CommandWhen) => Promise<{
         revision: number;
     }>;
 };

package/dist/commands.js

@@ -619,18 +619,20 @@ export const BUILTIN_COMMANDS = Object.freeze(BUILTIN_COMMAND_TABLE.trim()
 }));
 export function commandClient(transport) {
     return {
-        register: (id, revision, declaration, state) => transport.request("commands.register", {
+        register: (id, revision, declaration, state, when) => transport.request("commands.register", {
             id,
             revision,
             declaration,
             state,
+            ...(when ? { when: when } : {}),
         }),
         /** Remove the command from the menu and the binding table; the id is free again. */
         unregister: (id) => transport.request("commands.unregister", { id }),
-        update: (id, revision, state) => transport.request("commands.update", {
+        update: (id, revision, state, when) => transport.request("commands.update", {
             id,
             revision,
             state,
+            ...(when ? { when: when } : {}),
         }),
     };
 }

package/dist/host-capabilities.js

@@ -191,6 +191,7 @@ export const HOST_CAPABILITIES = {
                 { name: "video.view.release", needs: "processing.video" },
                 { name: "video.render.set", needs: "processing.video" },
                 { name: "video.render.release", needs: "processing.video" },
+                { name: "video.shaders.set", needs: "processing.video" },
             ],
             name: "processing.video",
             requires: ["playback.read"],

package/dist/player-runtime.d.ts

@@ -18,6 +18,7 @@ export { BINDING_INPUTS } from "./plugin/bindings.ts";
 export { OSD_LIMITS } from "./plugin/osd.ts";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.ts";
 export { SUBTITLE_LIMITS } from "./plugin/subtitles.ts";
+export { VIDEO_PROCESSING_LIMITS } from "./processing.ts";
 export { THEME_PALETTES } from "./palettes.ts";
 export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.ts";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.ts";

package/dist/player-runtime.js

@@ -16,6 +16,7 @@ export { BINDING_INPUTS } from "./plugin/bindings.js";
 export { OSD_LIMITS } from "./plugin/osd.js";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.js";
 export { SUBTITLE_LIMITS } from "./plugin/subtitles.js";
+export { VIDEO_PROCESSING_LIMITS } from "./processing.js";
 export { THEME_PALETTES } from "./palettes.js";
 export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.js";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.js";

package/dist/plugin/commands.js

@@ -4,7 +4,20 @@ import { checkBindings } from "./bindings.js";
 import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, MENU_IDS } from "../commands.js";
 import { ImageHandle } from "./ui.js";
 import { isTextValue, textProblem } from "../i18n.js";
+import { conditionJson, isCondition } from "./when.js";
 const value = (item) => typeof item === "function" ? item() : item;
+/** A field's value, or `fallback` (and its condition noted) for a condition. */
+function field(item, fallback, name, when) {
+    if (!isCondition(item))
+        return value(item);
+    when[name] = conditionJson(item);
+    return fallback;
+}
+/** How the player's log names a command: its title, else its id. */
+const label = (options) => {
+    const title = options.title ?? options.path?.at(-1);
+    return `command "${typeof title === "string" ? title : options.id}"`;
+};
 /** Validate options and build the wire declaration. */
 function declare(options) {
     const path = options.path ?? [];
@@ -88,13 +101,18 @@ class CommandHandle {
     #disposed = false;
     #registered = false;
     #pump;
+    #label;
+    /** Where the plugin added it, for the player's log. */
+    #where;
     #binding;
     constructor(scope, options) {
         const runtime = scope.runtime;
+        this.#where = runtime.callSite();
         if (runtime.commands.has(options.id))
             throw failure("conflict", `command ${options.id} is already declared`);
         this.id = options.id;
         this.#scope = scope;
+        this.#label = label(options);
         this.#spec = {
             enabled: options.enabled ?? true,
             checked: options.checked ?? null,
@@ -105,15 +123,15 @@ class CommandHandle {
         // The host requires a strictly increasing revision per update; the
         // registration itself is revision 1, so every later state follows it.
         const previous = removing(runtime).get(this.id);
-        this.#pump = new Latest(async (state) => {
+        this.#pump = new Latest(async ({ state, when }) => {
             const revision = ++this.#revision;
             if (revision === 1) {
                 await previous;
-                await runtime.host.commands.register(this.id, 1, declaration, state);
+                await runtime.host.commands.register(this.id, 1, declaration, state, when);
                 this.#registered = true;
             }
             else
-                await runtime.host.commands.update(this.id, revision, state);
+                await runtime.host.commands.update(this.id, revision, state, when);
         });
         const initial = this.#state();
         this.#last = JSON.stringify(initial);
@@ -127,8 +145,22 @@ class CommandHandle {
         this.#binding = runtime.bind(() => this.#sync());
         scope.add(this);
     }
+    /**
+     * The state to send. A condition field is sent as a placeholder with the
+     * condition in `when`: the player evaluates it. Each function field is
+     * evaluated under its own name, so what it reads is reported as this
+     * command's (`Runtime.reader`).
+     */
     #state() {
-        const reason = value(this.#spec.reason);
+        const runtime = this.#scope.runtime;
+        const spec = this.#spec;
+        const as = (name, read) => runtime.reader(`${this.#label} ${name}`, this.#where, read, name === "enabled" || name === "checked");
+        // enabled and checked first: what they read is reported as theirs
+        // (a condition can replace them), not as the reason's.
+        const when = {};
+        const enabled = as("enabled", () => field(spec.enabled, true, "enabled", when));
+        const checked = as("checked", () => field(spec.checked, false, "checked", when));
+        const reason = as("reason", () => value(spec.reason));
         if (reason !== null && typeof reason !== "string") {
             const problem = isTextValue(reason)
                 ? textProblem(reason)
@@ -136,12 +168,13 @@ class CommandHandle {
             if (problem)
                 throw failure("invalid", `command ${this.id}: ${problem}`);
         }
-        return {
-            enabled: value(this.#spec.enabled),
-            checked: value(this.#spec.checked),
-            busy: value(this.#spec.busy),
+        const state = {
+            enabled,
+            checked,
+            busy: as("busy", () => value(spec.busy)),
             reason,
         };
+        return Object.keys(when).length ? { state, when } : { state };
     }
     #sync() {
         if (this.#disposed)

package/dist/plugin/runtime.d.ts

@@ -1,5 +1,17 @@
 import type { Json, LocalServices, Transport, Wire } from "../wire.ts";
 import type { App, Disposable, Locale, PluginError, 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
+ * only when the player is told.
+ */
+export type Why = () => string;
+/**
+ * Events the player wakes a stopped plugin for (player 0.5.21): a listener
+ * of one does not keep the plugin running. They follow deliberate changes
+ * (an install, a key edit, the palette, a resolver), not playback.
+ */
+export declare const WAKE_EVENTS: readonly string[];
 export interface PluginManifest {
     id: string;
     capabilities: string[];
@@ -58,6 +70,18 @@ export declare class Runtime {
      * on it, so the event counts as listened to while the binding reads it.
      */
     reading(event: string): void;
+    /**
+     * Evaluate `read` as `label`, added at `where`: the state it reads is
+     * reported as read by it. `field`: a command's `enabled` or `checked`,
+     * which a `plugin.when` condition can replace.
+     */
+    reader<T>(label: string, where: (() => string | undefined) | undefined, read: () => T, field?: boolean): T;
+    /**
+     * Where the plugin's code called into the SDK: the first stack frame
+     * outside the SDK, as a path relative to the plugin's directory and a
+     * line (`main.ts:353`). Captured now, formatted when asked.
+     */
+    callSite(): () => string | undefined;
     /** Coalesce: one evaluation pass per microtask turn, however many changes. */
     invalidate(): void;
     /**
@@ -74,7 +98,13 @@ export declare class Runtime {
      * state, a binding that reads it. Nothing when nothing subscribed to it
      * (no capability, or the service did not start).
      */
-    hold(event: string): Disposable;
+    hold(event: string, why?: Why): Disposable;
+    /**
+     * Why the plugin listens to each event it really listens to (mirrors
+     * left out), as the player's log says it: for {@link TestHost} and
+     * `vestra-plugin test`.
+     */
+    listening(): Map<string, string[]>;
     /** Raw transport events the host pushes without a subscription. */
     raw(event: string, listener: Listener): Disposable;
 }

package/dist/plugin/runtime.js

@@ -1,6 +1,36 @@
 /** Shared machinery behind every scope: invocation, update passes, events. */
 import { createWire, HostError } from "../wire.js";
 import { LOCALES } from "../i18n.js";
+import { basename, isAbsolute, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The SDK's own files (`src/` or `dist/`): left out of a call site. */
+const SDK_DIRECTORY = fileURLToPath(new URL("..", import.meta.url));
+/**
+ * Events the player wakes a stopped plugin for (player 0.5.21): a listener
+ * of one does not keep the plugin running. They follow deliberate changes
+ * (an install, a key edit, the palette, a resolver), not playback.
+ */
+export const WAKE_EVENTS = [
+    "packages.changed",
+    "bindings.changed",
+    "appearance.changed",
+    "resolvers.fileTypes",
+];
+/**
+ * The state each event keeps current, and whether `plugin.when` can say
+ * the same without the plugin running.
+ */
+const STATE = {
+    "source.state": { name: "plugin.player.state", when: true },
+    "window.state": { name: "plugin.window.state", when: true },
+    "appearance.changed": { name: "plugin.appearance", when: true },
+    "timeline.changed": { name: "plugin.timeline.marks", when: false },
+    "playback.backend": { name: "plugin.subtitles.state", when: false },
+    "resolvers.fileTypes": {
+        name: "plugin.resolvers.fileTypes",
+        when: false,
+    },
+};
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export function toError(error) {
     if (error instanceof Error) {
@@ -89,8 +119,10 @@ export class Runtime {
     #transport;
     /** Each binding with the events whose state it read last time (held). */
     #bindings = new Map();
-    /** The events read by the binding being evaluated. */
+    /** The events read by the binding being evaluated, with who read them. */
     #reads;
+    /** Who reads now (a command's field and where it was added). */
+    #reader;
     #scheduled = false;
     #events = new Map();
     views = new Map();
@@ -171,26 +203,98 @@ export class Runtime {
      * on it, so the event counts as listened to while the binding reads it.
      */
     reading(event) {
-        this.#reads?.add(event);
+        const reads = this.#reads;
+        if (!reads || reads.has(event))
+            return;
+        const reader = this.#reader;
+        const state = STATE[event];
+        reads.set(event, () => {
+            const read = state?.name ?? event;
+            const site = reader?.where?.();
+            const at = site ? ` (${site})` : "";
+            if (!reader)
+                return `a binding reads ${read}`;
+            if (!reader.field)
+                return `${reader.label} reads ${read}${at}`;
+            const hint = state?.when ? " — use plugin.when" : "";
+            return `${reader.label} is a function that reads ${read}${at}${hint}`;
+        });
+    }
+    /**
+     * Evaluate `read` as `label`, added at `where`: the state it reads is
+     * reported as read by it. `field`: a command's `enabled` or `checked`,
+     * which a `plugin.when` condition can replace.
+     */
+    reader(label, where, read, field = false) {
+        const outer = this.#reader;
+        this.#reader = { label, where, field };
+        try {
+            return read();
+        }
+        finally {
+            this.#reader = outer;
+        }
+    }
+    /**
+     * Where the plugin's code called into the SDK: the first stack frame
+     * outside the SDK, as a path relative to the plugin's directory and a
+     * line (`main.ts:353`). Captured now, formatted when asked.
+     */
+    callSite() {
+        const limit = Error.stackTraceLimit;
+        Error.stackTraceLimit = 40;
+        const error = new Error();
+        Error.stackTraceLimit = limit;
+        let site = null;
+        return () => {
+            if (site === null)
+                site = this.#site(error.stack ?? "");
+            return site;
+        };
+    }
+    #site(stack) {
+        for (const line of stack.split("\n").slice(1)) {
+            const match = /\(?((?:file:\/\/)?[^()\s]+?):(\d+):\d+\)?\s*$/.exec(line);
+            if (!match)
+                continue;
+            let file = match[1];
+            if (file.startsWith("file:"))
+                try {
+                    file = fileURLToPath(file);
+                }
+                catch {
+                    continue;
+                }
+            const sdk = relative(SDK_DIRECTORY, file);
+            if (!isAbsolute(file) || !(sdk.startsWith("..") || isAbsolute(sdk)))
+                continue;
+            const inside = relative(this.directory, file);
+            const shown = inside.startsWith("..") || isAbsolute(inside) ? basename(file) : inside;
+            return `${shown.replaceAll("\\", "/")}:${match[2]}`;
+        }
+        return undefined;
     }
     /** Evaluate one binding, holding the events whose state it read. */
     #evaluate(evaluate, held) {
-        const reads = new Set();
+        const reads = new Map();
         const outer = this.#reads;
+        const reader = this.#reader;
         this.#reads = reads;
+        this.#reader = undefined;
         try {
             evaluate();
         }
         finally {
             this.#reads = outer;
+            this.#reader = reader;
             for (const [event, hold] of held)
                 if (!reads.has(event)) {
                     held.delete(event);
                     void hold.dispose();
                 }
-            for (const event of reads)
+            for (const [event, why] of reads)
                 if (!held.has(event))
-                    held.set(event, this.hold(event));
+                    held.set(event, this.hold(event, why));
         }
     }
     /** Coalesce: one evaluation pass per microtask turn, however many changes. */
@@ -224,19 +328,24 @@ export class Runtime {
         let entry = this.#events.get(event);
         const created = !entry;
         if (!entry) {
-            entry = { listeners: new Set(), active: 0 };
+            entry = { listeners: new Set(), active: 0, whys: new Map() };
             this.#events.set(event, entry);
         }
         const group = entry;
         group.listeners.add(listener);
-        if (!mirror)
+        const token = {};
+        if (!mirror) {
             group.active++;
+            group.whys.set(token, listenerWhy(this.callSite()));
+        }
         if (created && (needs === null || this.can(needs))) {
             group.told = group.active > 0;
+            const whys = group.told ? allWhys(group) : undefined;
+            group.toldWhy = whys?.join("\n");
             group.off = this.host.events.subscribe(event, (data) => {
                 for (const each of [...group.listeners])
                     each(data);
-            }, !group.told);
+            }, !group.told, whys);
             this.starting(group.off, (error) => console.error(`[${this.manifest.id}] subscribe ${event}:`, error));
         }
         else
@@ -250,6 +359,7 @@ export class Runtime {
                 group.listeners.delete(listener);
                 if (!mirror)
                     group.active--;
+                group.whys.delete(token);
                 if (this.#events.get(event) !== group)
                     return;
                 if (group.listeners.size)
@@ -265,11 +375,13 @@ export class Runtime {
      * state, a binding that reads it. Nothing when nothing subscribed to it
      * (no capability, or the service did not start).
      */
-    hold(event) {
+    hold(event, why) {
         const group = this.#events.get(event);
         if (!group)
             return { dispose: async () => { } };
         group.active++;
+        const token = {};
+        group.whys.set(token, why ?? listenerWhy(this.callSite()));
         this.#tell(event, group);
         let held = true;
         return {
@@ -278,32 +390,62 @@ export class Runtime {
                     return;
                 held = false;
                 group.active--;
+                group.whys.delete(token);
                 if (this.#events.get(event) === group)
                     this.#tell(event, group);
             },
         };
     }
-    /** Tell the player when `group` changes between mirror and listener. */
+    /**
+     * Tell the player when `group` changes between mirror and listener, and
+     * why it listens when that changed.
+     */
     #tell(event, group) {
         const off = group.off;
+        if (!off)
+            return;
         const active = group.active > 0;
-        if (!off || group.told === active)
+        const whys = active ? allWhys(group) : undefined;
+        const why = whys?.join("\n");
+        if (group.told === active && group.toldWhy === why)
             return;
         group.told = active;
+        group.toldWhy = why;
         // Part of activation while it runs: the player classifies the plugin
         // at its ready, which must see this mark. A failure is not one of
         // activation (an older player never refuses it).
         const told = off
-            .then(() => this.host.events.listen(event, active))
+            .then(() => this.host.events.listen(event, active, whys))
             .catch(() => { });
         this.starting(told, () => { });
     }
+    /**
+     * Why the plugin listens to each event it really listens to (mirrors
+     * left out), as the player's log says it: for {@link TestHost} and
+     * `vestra-plugin test`.
+     */
+    listening() {
+        const result = new Map();
+        for (const [event, group] of this.#events)
+            if (group.active > 0)
+                result.set(event, allWhys(group));
+        return result;
+    }
     /** Raw transport events the host pushes without a subscription. */
     raw(event, listener) {
         const off = this.#transport.on(event, listener);
         return { dispose: async () => off() };
     }
 }
+/** A plugin listener's reason: where it was added. */
+const listenerWhy = (site) => () => {
+    const at = site();
+    return at ? `a listener added at ${at}` : "a listener";
+};
+/** Every active holder's reason in `group`, in the order they came, once each. */
+function allWhys(group) {
+    return [...new Set([...group.whys.values()].map((why) => why()))];
+}
 /** `plugin.app` from the start-up handshake (the runner's environment). */
 export function appInfo(raw, system = () => Promise.reject(failure("unavailable", "no player to ask"))) {
     const info = (raw ?? {});

package/dist/plugin/scope.d.ts

@@ -8,6 +8,7 @@ export declare class ScopeImpl implements Plugin {
     get dataDirectory(): string;
     get disposed(): boolean;
     readonly commands: import("./types.ts").Commands;
+    readonly when: import("./types.ts").When;
     readonly windows: import("./types.ts").Windows;
     readonly panels: import("./types.ts").Panels;
     readonly dialogs: import("./types.ts").Dialogs;
@@ -15,6 +16,7 @@ export declare class ScopeImpl implements Plugin {
     readonly video: {
         view: () => import("./types.ts").VideoView;
         render: () => import("./types.ts").RenderOptions;
+        shaders: (id?: string) => import("./types.ts").VideoShaders;
         upscaling: import("./types.ts").VideoUpscaling;
         filter(id: string): import("./types.ts").VideoFilter;
     };

package/dist/plugin/scope.js

@@ -1,6 +1,7 @@
 /** Scopes own handles. Disposal runs newest first and never throws. */
 import { failure, toError } from "./runtime.js";
 import { commands } from "./commands.js";
+import { WHEN } from "./when.js";
 import { dialogs, panels, ui, windows } from "./ui.js";
 import { timeline } from "./timeline.js";
 import { drops } from "./drops.js";
@@ -10,6 +11,7 @@ import { i18n } from "./language.js";
 import { player } from "./player.js";
 import { audioFilters, videoFilters } from "./filters.js";
 import { videoRender, videoView } from "./view.js";
+import { videoShaders } from "./shaders.js";
 import { subtitles } from "./subtitles.js";
 import { mediaCapture } from "./media.js";
 import { resolvers } from "./resolvers.js";
@@ -41,6 +43,7 @@ export class ScopeImpl {
         return this.#disposed || (this.#parent?.disposed ?? false);
     }
     commands = commands(this);
+    when = WHEN;
     windows = windows(this);
     panels = panels(this);
     dialogs = dialogs(this);
@@ -49,6 +52,7 @@ export class ScopeImpl {
         ...videoFilters(this),
         view: () => videoView(this),
         render: () => videoRender(this),
+        shaders: (id) => videoShaders(this, id),
         upscaling: videoUpscaling(this),
     };
     audio = audioFilters(this);

package/dist/plugin/shaders.d.ts

@@ -0,0 +1,9 @@
+import type { ScopeImpl } from "./scope.ts";
+import type { VideoShaders } from "./types.ts";
+/** The handle id when `shaders()` is called without one. */
+export declare const DEFAULT_SHADERS_ID = "shaders";
+/** Why `paths` would be refused here (`null` when it may be sent). */
+export declare function shaderListProblem(paths: unknown): string | null;
+/** Why a handle id would be refused (`null` when valid). */
+export declare function shaderIdProblem(id: unknown): string | null;
+export declare function videoShaders(scope: ScopeImpl, id?: string): VideoShaders;