@vestra-player/sdk 1.5.39 → 1.5.41

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.5.41
+
+**Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Only how the player draws the bottom bar's strip of command buttons changes (player 0.5.22); a plugin's declarations and a bar that places `BarButtons` stay as they are.
+
+- **`@vestra/bar-buttons.slint`** (the read-only copy of the player's widget library): every enabled button of the strip draws its icon in the accent colour (`Theme.accent`, `Theme.accent-press` while pressed; `Theme.icon-disabled` when disabled), plugin images (`plugin.ui.image`) included. Before, icons were in the text colour and only a checked toggle in the accent. A checked command (`checked: true`, the sidebar toggle while the sidebar is on) now shows a 4px dot in the icon's colour centred under the icon, as the macOS Dock marks a running app; the accessibility checked state is unchanged.
+- _Commands_ (reference), `CommandOptions.button` and `TestHost.barButtons[].checked` describe the new look.
+
+## 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.

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/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/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;

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";
@@ -42,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);

package/dist/plugin/testing.d.ts

@@ -271,7 +271,26 @@ export interface FakeCommand {
          */
         reason?: string | null;
     };
-    /** The command state the player last received (after the update pass). */
+    /**
+     * The conditions the plugin sent for `enabled` and `checked`
+     * (`plugin.when`, wire form), `undefined` without. Like the player, the
+     * host evaluates them in {@link FakeCommand.state} against `source`,
+     * `mainWindow.fullscreen`, `appearance` and `language`.
+     *
+     * @since 1.5.40
+     */
+    when?: {
+        /** The condition of `enabled`. */
+        enabled?: Json;
+        /** The condition of `checked`. */
+        checked?: Json;
+    };
+    /**
+     * The command state as the player shows it: what the plugin last sent
+     * (after the update pass), with the fields given as conditions
+     * (`plugin.when`) evaluated now. With an `enabled` condition, `reason`
+     * is `null` while the command is enabled and not busy.
+     */
     state: {
         /** `false` when the plugin disabled the command. */
         enabled: boolean;
@@ -351,7 +370,7 @@ export interface FakeBarButton {
     readonly order: number;
     /** Clickable: the command is enabled and not busy. */
     readonly enabled: boolean;
-    /** Drawn in the accent colour: the command is checked. */
+    /** Shown with the on dot under its icon: the command is checked. */
     readonly checked: boolean;
     /**
      * The tooltip without the key: the command's shown title (trailing "…"
@@ -548,6 +567,16 @@ export declare class TestHost implements Transport {
      * @since 1.5.38
      */
     readonly listening: Set<string>;
+    /**
+     * Why the plugin listens to each event of {@link TestHost.listening}:
+     * every listener and every binding that reads its state, as the
+     * player's log says them (`a listener added at main.ts:12`,
+     * `command "Save" enabled is a function that reads plugin.player.state
+     * (main.ts:40) — use plugin.when`), in the order they came.
+     *
+     * @since 1.5.40
+     */
+    readonly listeningWhy: Map<string, string[]>;
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with
@@ -2588,6 +2617,32 @@ export declare class TestHost implements Transport {
      * @since 1.0.0
      */
     close(): void;
+    /**
+     * Why the player would keep this plugin running while nothing uses it
+     * (lazy activation, player 0.5.21), one line per reason, as the player's
+     * log says it: an event it listens to that is not one the player wakes
+     * it for (with what listens and where it was added), its mounted panel,
+     * its open windows. Empty: the player may stop it while idle and start
+     * it again on its next use. Filter chains, streams, jobs and the like
+     * (which also keep a plugin running) are not listed.
+     *
+     * @capability None.
+     * @since 1.5.40
+     *
+     * @example Check that a plugin can be stopped while idle
+     * The test fails if the plugin keeps running for no reason after it
+     * starts, and names the reason (a command whose `enabled` reads
+     * `plugin.player.state`, say: give it a `plugin.when` condition). The
+     * player stops such a plugin while nothing uses it and starts it again
+     * on its next use, so it costs no process meanwhile.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * assert.deepEqual(host.keepsRunning, []);
+     * ```
+     */
+    get keepsRunning(): string[];
 }
 /**
  * Activate a plugin against a test host, the way the player's runner does: