@vestra-player/sdk 1.5.36 → 1.5.38

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 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`).
+
+- **Mirror subscriptions** (player 0.5.18): the SDK's own subscriptions that keep `plugin.player.state`, `plugin.window.state`, `plugin.timeline.marks`, `plugin.subtitles.state`, `plugin.appearance`, `plugin.resolvers.fileTypes` and panel positions current are sent as `events.subscribe { event, mirror: true }`. When the plugin adds a listener (an `onChange`, `onEnd`, `onFileTypesChange`) or a binding that reads that state (a command's `enabled`, `checked`, `busy` or `reason` function, a view's `bind`), the SDK sends `events.subscribe { event }` again; when the last one goes, `events.subscribe { event, mirror: true }`. A change made while the plugin activates is sent before it reports ready, so the player sees it when it classifies the plugin. The player keeps a plugin whose subscriptions are all mirrors parkable; the plugin sees no difference.
+- **`PluginInfo.process`** (player 0.5.18, optional): for a running plugin, `"running"` while its process runs, `"idle"` while the player stopped it because nothing used it (its entries stay and its next use starts it). `state` stays `"running"`, and a change of `process` alone does not fire `packages.onChange`.
+- **`TestHost.listening`**: the subscribed events the plugin really listens to (`subscriptions` without the mirrors).
+- _Plugins_ (concepts) has a new section, _Idle plugins are stopped_: what stays while a plugin is stopped, what keeps it running (listeners, bindings that read state, windows, panels, chains, streams…) and what does not (network requests, timers and promises the player does not see: as in Chrome Manifest V3, keep what they need in session storage).
+
+## 1.5.37
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The new API needs player 0.5.16 (`"minPlayerVersion": "0.5.16"`): older players do not load a plugin that declares the new capability `video.upscaling` (an unknown capability). A plugin that does not use it sees no difference.
+
+- **`plugin.video.upscaling`** (player 0.5.16): the GPU's video upscaler, NVIDIA RTX Video Super Resolution on Windows. `state()` reports whether it works now (`available`) and why not (`reason`, `{ code, message }` with the stable codes of `UpscalingReasonCode`: `platform`, `no-gpu`, `driver`, `gpu-unsupported`, `rendering`, `adapter`, `decoding`, `unchecked`; a newer player may add codes), whether this plugin turned it on (`enabled`), and whether the player asked the GPU to upscale now (`requested`, with the scale `factor`). `set(enabled)` turns this plugin's request on or off and resolves with the new state; `true` rejects with `unsupported` where upscaling cannot work in this run: every reason except `decoding` (it can pass with the next file) and except `rendering` while GPU rendering is still starting, which are accepted and kept; `false` is always accepted and answered at once without the GPU check (before any check: `available: false` with `unchecked`); `invalid` for a non-boolean. The player checks the GPU once, at the first `state()` or `set(true)` (it wakes a sleeping discrete GPU, so the examples ask on the first pick of the item, not while the plugin starts), puts the upscaler last in the video filter chain scaled to the area the video is shown in (only above 1×), follows size changes, and takes it out when the last plugin turns it off or stops. There is no "upscaling active" signal: on Windows the user must also turn on Super Resolution in the NVIDIA app, which no program can read. New types `VideoUpscaling`, `UpscalingState`, `UpscalingReason`, `UpscalingReasonCode`.
+- **New capability `video.upscaling`** ("Upscale the video with the GPU's video upscaler", not highlighted in the store: it changes only how the picture is scaled while the plugin runs and touches no data), last in `CAPABILITIES`; both requests need it and reject with `capability` without it. The player's capability table copy, `CAPABILITY_INFO`, `vestra-plugin check` and the editor plugin know it.
+- **`TestHost.upscaling`** models the player: preset `reason` (`null`: it works) and `factor`, read `enabled` and `checked` (whether the plugin made the player check the GPU), set `renderingStarting`; `set(true)` refuses with `unsupported` unless the reason is `decoding`, or `rendering` with `renderingStarting`; `set(false)` checks nothing (`unchecked` before any check).
+- _Video and audio processing_ and _Platforms_ describe the upscaler.
+
 ## 1.5.36
 
 **Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed.

package/README.md

@@ -15,6 +15,7 @@
   <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a> ·
   <a href="https://vestrasys.github.io/vestra-player-sdk/llms.txt">llms.txt</a>
 </p>
+
 ## Features
 
 - **One typed API** (`vestra/1`) for commands and menus, windows, panels, settings pages, on-screen messages, playback state and control, video and audio filters, and generated streams.

package/dist/api-requests.js

@@ -143,4 +143,6 @@ export const API_REQUESTS = Object.freeze({
     "Rendering.state": [{ method: "rendering.state" }],
     "Rendering.setPreference": [{ method: "rendering.setPreference" }],
     "Rendering.restartPlayer": [{ method: "rendering.restart" }],
+    "VideoUpscaling.state": [{ method: "video.upscaling.state" }],
+    "VideoUpscaling.set": [{ method: "video.upscaling.set" }],
 });

package/dist/host-capabilities.js

@@ -354,6 +354,17 @@ export const HOST_CAPABILITIES = {
             residency: "none",
             risky: true,
         },
+        {
+            label: "Upscale the video with the GPU's video upscaler",
+            methods: [
+                { name: "video.upscaling.state", needs: "video.upscaling" },
+                { name: "video.upscaling.set", needs: "video.upscaling" },
+            ],
+            name: "video.upscaling",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
     ],
     uncapable: [
         { name: "packages.list", needs: null },

package/dist/plugin/appearance.js

@@ -29,6 +29,7 @@ class AppearanceService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("appearance.changed", (data) => {
             const event = data;
             const language = preference(event?.language);
@@ -39,7 +40,7 @@ class AppearanceService {
             const theme = event?.theme;
             if (theme && THEMES.includes(theme))
                 this.accept(theme);
-        });
+        }, "events", true);
     }
     accept(theme) {
         if (theme === this.theme)
@@ -51,7 +52,13 @@ class AppearanceService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("appearance.changed");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 const appearanceOf = (runtime) => runtime.service("appearance", () => new AppearanceService(runtime));
@@ -60,6 +67,7 @@ export function appearance(scope) {
     return {
         get theme() {
             service().start();
+            scope.runtime.reading("appearance.changed");
             return service().theme;
         },
         onChange(listener) {
@@ -80,6 +88,7 @@ export function appearance(scope) {
         },
         get language() {
             service().start();
+            scope.runtime.reading("appearance.changed");
             return service().language;
         },
         async setLanguage(language) {

package/dist/plugin/packages.js

@@ -164,6 +164,9 @@ const info = (plugin) => Object.freeze({
         ...(warning.slot === undefined ? {} : { slot: warning.slot }),
         ...(warning.owner === undefined ? {} : { owner: warning.owner }),
     }))),
+    ...(plugin.process === "running" || plugin.process === "idle"
+        ? { process: plugin.process }
+        : {}),
     ...(plugin.display
         ? {
             display: Object.freeze({

package/dist/plugin/player.js

@@ -116,7 +116,9 @@ export class PlayerService {
     output;
     constructor(runtime) {
         this.runtime = runtime;
-        runtime.on("source.state", (data) => this.accept(data));
+        // The SDK's copy of the state (a mirror): a plugin listens through
+        // `watch` and the bindings that read `state`.
+        runtime.on("source.state", (data) => this.accept(data), "events", true);
         this.output = new Latest(async ({ volume, muted }) => {
             if (volume !== undefined)
                 await runtime.host.playback.set("volume", volume);
@@ -144,9 +146,11 @@ export class PlayerService {
     }
     watch(watcher) {
         this.#watchers.add(watcher);
+        const held = this.runtime.hold("source.state");
         return {
             dispose: async () => {
                 this.#watchers.delete(watcher);
+                await held.dispose();
             },
         };
     }
@@ -429,6 +433,7 @@ export function player(scope) {
     const service = () => playerOf(scope.runtime);
     return {
         get state() {
+            scope.runtime.reading("source.state");
             return service().state;
         },
         onChange(listener) {

package/dist/plugin/resolvers.js

@@ -26,11 +26,12 @@ class FileTypesService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("resolvers.fileTypes", (data) => {
             const types = data?.fileTypes;
             if (Array.isArray(types) && types.every((t) => typeof t === "string"))
                 this.accept(types);
-        });
+        }, "events", true);
         // What changed between the start-up read and the subscription.
         const window = windowOf(this.#runtime);
         void window.read().then(() => {
@@ -50,7 +51,13 @@ class FileTypesService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("resolvers.fileTypes");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 const fileTypesOf = (runtime) => runtime.service("fileTypes", () => new FileTypesService(runtime));
@@ -58,6 +65,7 @@ export const resolvers = (scope) => ({
     get fileTypes() {
         const service = fileTypesOf(scope.runtime);
         service.start();
+        scope.runtime.reading("resolvers.fileTypes");
         return service.types;
     },
     onFileTypesChange(listener) {

package/dist/plugin/runtime.d.ts

@@ -53,15 +53,28 @@ export declare class Runtime {
     starting<T>(work: Promise<T>, report: (error: unknown) => void): Promise<T>;
     activated(): Promise<void>;
     bind(evaluate: () => void): Disposable;
+    /**
+     * A service's state for `event` is read: a binding evaluated now depends
+     * on it, so the event counts as listened to while the binding reads it.
+     */
+    reading(event: string): void;
     /** Coalesce: one evaluation pass per microtask turn, however many changes. */
     invalidate(): void;
     /**
      * Host events with one `events.subscribe` per name, however many listeners.
      * Without the `events` capability the listener simply never fires.
+     * `mirror`: the SDK's own copy of the state (`plugin.player.state` and
+     * the like), not a listener of the plugin's (see {@link EventGroup}).
      */
     on(event: string, listener: Listener, 
     /** The capability the event needs; `null`: none. */
-    needs?: string | null): Disposable;
+    needs?: string | null, mirror?: boolean): Disposable;
+    /**
+     * Count `event` as listened to while held: a watcher of a service's
+     * state, a binding that reads it. Nothing when nothing subscribed to it
+     * (no capability, or the service did not start).
+     */
+    hold(event: string): Disposable;
     /** Raw transport events the host pushes without a subscription. */
     raw(event: string, listener: Listener): Disposable;
 }

package/dist/plugin/runtime.js

@@ -87,7 +87,10 @@ export class Runtime {
     startup = new Set();
     #activating = true;
     #transport;
-    #bindings = new Set();
+    /** Each binding with the events whose state it read last time (held). */
+    #bindings = new Map();
+    /** The events read by the binding being evaluated. */
+    #reads;
     #scheduled = false;
     #events = new Map();
     views = new Map();
@@ -149,14 +152,47 @@ export class Runtime {
         this.#activating = false;
     }
     bind(evaluate) {
-        this.#bindings.add(evaluate);
+        const held = new Map();
+        this.#bindings.set(evaluate, held);
         this.invalidate();
         return {
             dispose: async () => {
+                if (this.#bindings.get(evaluate) !== held)
+                    return;
                 this.#bindings.delete(evaluate);
+                for (const hold of held.values())
+                    await hold.dispose();
+                held.clear();
             },
         };
     }
+    /**
+     * A service's state for `event` is read: a binding evaluated now depends
+     * on it, so the event counts as listened to while the binding reads it.
+     */
+    reading(event) {
+        this.#reads?.add(event);
+    }
+    /** Evaluate one binding, holding the events whose state it read. */
+    #evaluate(evaluate, held) {
+        const reads = new Set();
+        const outer = this.#reads;
+        this.#reads = reads;
+        try {
+            evaluate();
+        }
+        finally {
+            this.#reads = outer;
+            for (const [event, hold] of held)
+                if (!reads.has(event)) {
+                    held.delete(event);
+                    void hold.dispose();
+                }
+            for (const event of reads)
+                if (!held.has(event))
+                    held.set(event, this.hold(event));
+        }
+    }
     /** Coalesce: one evaluation pass per microtask turn, however many changes. */
     invalidate() {
         if (this.#scheduled)
@@ -164,9 +200,11 @@ export class Runtime {
         this.#scheduled = true;
         queueMicrotask(() => {
             this.#scheduled = false;
-            for (const evaluate of this.#bindings) {
+            for (const [evaluate, held] of [...this.#bindings]) {
+                if (this.#bindings.get(evaluate) !== held)
+                    continue;
                 try {
-                    evaluate();
+                    this.#evaluate(evaluate, held);
                 }
                 catch (error) {
                     console.error(`[${this.manifest.id}] binding failed:`, error);
@@ -177,36 +215,89 @@ export class Runtime {
     /**
      * Host events with one `events.subscribe` per name, however many listeners.
      * Without the `events` capability the listener simply never fires.
+     * `mirror`: the SDK's own copy of the state (`plugin.player.state` and
+     * the like), not a listener of the plugin's (see {@link EventGroup}).
      */
     on(event, listener, 
     /** The capability the event needs; `null`: none. */
-    needs = "events") {
+    needs = "events", mirror = false) {
         let entry = this.#events.get(event);
+        const created = !entry;
         if (!entry) {
-            entry = { listeners: new Set() };
+            entry = { listeners: new Set(), active: 0 };
             this.#events.set(event, entry);
-            if (needs === null || this.can(needs)) {
-                const group = entry;
-                entry.off = this.host.events.subscribe(event, (data) => {
-                    for (const each of [...group.listeners])
-                        each(data);
-                });
-                this.starting(entry.off, (error) => console.error(`[${this.manifest.id}] subscribe ${event}:`, error));
-            }
         }
-        entry.listeners.add(listener);
         const group = entry;
+        group.listeners.add(listener);
+        if (!mirror)
+            group.active++;
+        if (created && (needs === null || this.can(needs))) {
+            group.told = group.active > 0;
+            group.off = this.host.events.subscribe(event, (data) => {
+                for (const each of [...group.listeners])
+                    each(data);
+            }, !group.told);
+            this.starting(group.off, (error) => console.error(`[${this.manifest.id}] subscribe ${event}:`, error));
+        }
+        else
+            this.#tell(event, group);
+        let listening = true;
         return {
             dispose: async () => {
+                if (!listening)
+                    return;
+                listening = false;
                 group.listeners.delete(listener);
-                if (group.listeners.size || this.#events.get(event) !== group)
+                if (!mirror)
+                    group.active--;
+                if (this.#events.get(event) !== group)
                     return;
+                if (group.listeners.size)
+                    return this.#tell(event, group);
                 this.#events.delete(event);
                 const off = await group.off?.catch(() => undefined);
                 await off?.().catch(() => { });
             },
         };
     }
+    /**
+     * Count `event` as listened to while held: a watcher of a service's
+     * state, a binding that reads it. Nothing when nothing subscribed to it
+     * (no capability, or the service did not start).
+     */
+    hold(event) {
+        const group = this.#events.get(event);
+        if (!group)
+            return { dispose: async () => { } };
+        group.active++;
+        this.#tell(event, group);
+        let held = true;
+        return {
+            dispose: async () => {
+                if (!held)
+                    return;
+                held = false;
+                group.active--;
+                if (this.#events.get(event) === group)
+                    this.#tell(event, group);
+            },
+        };
+    }
+    /** Tell the player when `group` changes between mirror and listener. */
+    #tell(event, group) {
+        const off = group.off;
+        const active = group.active > 0;
+        if (!off || group.told === active)
+            return;
+        group.told = active;
+        // 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))
+            .catch(() => { });
+        this.starting(told, () => { });
+    }
     /** Raw transport events the host pushes without a subscription. */
     raw(event, listener) {
         const off = this.#transport.on(event, listener);

package/dist/plugin/scope.d.ts

@@ -15,6 +15,7 @@ export declare class ScopeImpl implements Plugin {
     readonly video: {
         view: () => import("./types.ts").VideoView;
         render: () => import("./types.ts").RenderOptions;
+        upscaling: import("./types.ts").VideoUpscaling;
         filter(id: string): import("./types.ts").VideoFilter;
     };
     readonly audio: {

package/dist/plugin/scope.js

@@ -17,7 +17,7 @@ import { packages } from "./packages.js";
 import { osd } from "./osd.js";
 import { mainWindow } from "./window.js";
 import { bindingsApi } from "./bindings.js";
-import { clipboard, host, power, rendering, secrets, storage, system, tools, } from "./services.js";
+import { clipboard, host, power, rendering, secrets, storage, system, tools, videoUpscaling, } from "./services.js";
 export class ScopeImpl {
     runtime;
     #parent;
@@ -49,6 +49,7 @@ export class ScopeImpl {
         ...videoFilters(this),
         view: () => videoView(this),
         render: () => videoRender(this),
+        upscaling: videoUpscaling(this),
     };
     audio = audioFilters(this);
     subtitles = subtitles(this);

package/dist/plugin/services.d.ts

@@ -1,5 +1,5 @@
 import type { ScopeImpl } from "./scope.ts";
-import type { Clipboard, Host, Power, Rendering, Secrets, Storage, System, Tools } from "./types.ts";
+import type { Clipboard, Host, Power, Rendering, Secrets, Storage, System, Tools, VideoUpscaling } from "./types.ts";
 export declare const clipboard: (scope: ScopeImpl) => Clipboard;
 export declare const host: (scope: ScopeImpl) => Host;
 export declare const power: (scope: ScopeImpl) => Power;
@@ -113,3 +113,9 @@ export declare const SECRET_LIMITS: Readonly<{
 }>;
 export declare const secrets: (scope: ScopeImpl) => Secrets;
 export declare const rendering: (scope: ScopeImpl) => Rendering;
+/**
+ * `plugin.video.upscaling` (player 0.5.16): both requests need
+ * `video.upscaling`; the player answers once its GPU check ran (the first
+ * call starts it).
+ */
+export declare const videoUpscaling: (scope: ScopeImpl) => VideoUpscaling;

package/dist/plugin/services.js

@@ -1,7 +1,8 @@
 /**
  * Shared services: the clipboard, sleep prevention, showing and opening files
- * and links, secrets, session storage and the rendering choice go to the
- * host; external tools and settings files run in this plugin's own process.
+ * and links, secrets, session storage, the rendering choice and the video
+ * upscaler go to the host; external tools and settings files run in this
+ * plugin's own process.
  */
 import { existsSync, readFileSync, renameSync } from "node:fs";
 import { mkdir, open, rename, rm, stat } from "node:fs/promises";
@@ -497,3 +498,26 @@ export const rendering = (scope) => {
         },
     };
 };
+/**
+ * `plugin.video.upscaling` (player 0.5.16): both requests need
+ * `video.upscaling`; the player answers once its GPU check ran (the first
+ * call starts it).
+ */
+export const videoUpscaling = (scope) => {
+    const declared = () => {
+        if (!scope.runtime.can("video.upscaling"))
+            throw failure("capability", "video.upscaling must be declared in manifest");
+    };
+    return {
+        async state() {
+            declared();
+            return (await scope.runtime.host.video.upscalingState());
+        },
+        async set(enabled) {
+            declared();
+            if (typeof enabled !== "boolean")
+                throw failure("invalid", "enabled must be true or false");
+            return (await scope.runtime.host.video.upscalingSet(enabled));
+        },
+    };
+};

package/dist/plugin/subtitles.js

@@ -62,6 +62,8 @@ export const SUBTITLE_LIMITS = Object.freeze({
     /** Loads of every plugin in progress at the same time (8). */
     uploads: 8,
 });
+/** The events the subtitle state follows (it has none of its own). */
+const EVENTS = ["source.state", "playback.backend"];
 const raws = new WeakMap();
 const targets = new WeakMap();
 const CHUNK = 32 * 1024;
@@ -85,6 +87,7 @@ class SubtitleService {
     constructor(runtime) {
         this.#runtime = runtime;
         // No subtitle event exists: re-read when the source or backend changes.
+        // Mirrors: a plugin listens through `watch` and bindings.
         runtime.on("source.state", (data) => {
             const raw = data;
             const source = `${raw.stamp.generation}:${raw.phase}`;
@@ -92,8 +95,8 @@ class SubtitleService {
                 return;
             this.#source = source;
             void this.refresh().catch(() => { });
-        });
-        runtime.on("playback.backend", () => void this.refresh().catch(() => { }));
+        }, "events", true);
+        runtime.on("playback.backend", () => void this.refresh().catch(() => { }), "events", true);
         this.style = new Latest(async ({ style, options }) => {
             const expected = await this.expected(options);
             await this.#mutate(++this.#operation, (operationId) => runtime.host.subtitles.style({
@@ -106,12 +109,20 @@ class SubtitleService {
     }
     watch(watcher) {
         this.#watchers.add(watcher);
+        const held = EVENTS.map((event) => this.#runtime.hold(event));
         return {
             dispose: async () => {
                 this.#watchers.delete(watcher);
+                for (const hold of held.splice(0))
+                    await hold.dispose();
             },
         };
     }
+    /** A binding that reads the state follows both events. */
+    reading() {
+        for (const event of EVENTS)
+            this.#runtime.reading(event);
+    }
     /** Keep the newest view: older generations and older revisions are dropped. */
     accept(raw) {
         const old = this.raw;
@@ -258,6 +269,7 @@ export function subtitles(scope) {
     const host = () => scope.runtime.host.subtitles;
     return {
         get state() {
+            service().reading();
             return service().state;
         },
         onChange(listener) {

package/dist/plugin/testing.d.ts

@@ -15,7 +15,7 @@ import { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
-import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, ViewSettings } from "./types.ts";
+import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingReason, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
 import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
 import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
@@ -469,7 +469,8 @@ export interface MarkdownWire {
  *   {@link TestHost.app}, {@link TestHost.systemInfo},
  *   {@link TestHost.chapters}, {@link TestHost.audioDevices},
  *   {@link TestHost.secrets}, {@link TestHost.clipboard},
- *   {@link TestHost.tools}, {@link TestHost.rendering}.
+ *   {@link TestHost.tools}, {@link TestHost.rendering},
+ *   {@link TestHost.upscaling}.
  * - **Assert** on records: {@link TestHost.osd}, {@link TestHost.calls},
  *   {@link TestHost.sent}, {@link TestHost.conflicts},
  *   {@link TestHost.layout}, {@link TestHost.menus}, and many more.
@@ -534,6 +535,16 @@ export declare class TestHost implements Transport {
     readonly calls: Call[];
     /** The host events the plugin subscribed to (needs `events` etc.). */
     readonly subscriptions: Set<string>;
+    /**
+     * The subscribed events the plugin really listens to: an `onChange` and
+     * the like, or a binding that reads the state. The SDK's own copies of
+     * the state (what keeps `plugin.player.state` current) are left out.
+     * Empty means the player may stop the plugin while nothing uses it
+     * (unless it holds something else: a window, a panel, a filter…).
+     *
+     * @since 1.5.38
+     */
+    readonly listening: Set<string>;
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with
@@ -1703,6 +1714,65 @@ export declare class TestHost implements Transport {
         /** Accepted `restartPlayer` calls. */
         restarts: number;
     };
+    /**
+     * The GPU's video upscaler behind `plugin.video.upscaling` (player
+     * 0.5.16), answered as the player would:
+     *
+     * - `state()` and `set(true)` set `checked` (the player's one GPU check; a
+     *   plugin that should not wake the GPU while it starts can assert it is
+     *   still `false`) and report `available` from `reason` (`null`: it
+     *   works), this plugin's `enabled`, and `requested` with `factor` while
+     *   enabled, available and `factor` is above 1.
+     * - `set(true)` refuses with `unsupported` and the reason's message while
+     *   `reason` is set, unless its code is `decoding`, or `rendering` with
+     *   `renderingStarting` (GPU rendering still starting): those can pass
+     *   during the run, so the player keeps the request. Nothing changes when
+     *   it refuses.
+     * - `set(false)` always succeeds and does not check the GPU: before any
+     *   check it reports `available: false` with the reason `unchecked`.
+     *
+     * Inject other answers with `host.handle("video.upscaling.set", …)`. The
+     * defaults are a player where upscaling works and a 1080p video shown
+     * full screen on a 4K display (`factor` 2), whatever `systemInfo` says.
+     *
+     * @example Test the menu item on a computer without an RTX GPU
+     * The plugin's upscaling item is greyed out with the player's reason after
+     * the user first picks it. Starting the plugin checks nothing (`checked`
+     * stays false, so no GPU wakes up); the first pick reads the state, and
+     * `set(true)` would reject with `unsupported`, as in the player.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+     * import activate from "../main.ts";
+     *
+     * const host = new TestHost();
+     * host.upscaling.reason = { code: "no-gpu", message: "no NVIDIA GPU" };
+     * const { stop } = await startPlugin(activate, {
+     *   directory: new URL("..", import.meta.url),
+     *   host,
+     * });
+     * assert.equal(host.upscaling.checked, false); // starting woke no GPU
+     * const item = host.command("upscaling");
+     * await item.run(); // the first pick checks the GPU
+     * assert.equal(item.state.enabled, false); // greyed out
+     * assert.equal(item.state.reason, "no NVIDIA GPU"); // the player's message
+     * await stop();
+     * ```
+     *
+     * @since 1.5.37
+     */
+    readonly upscaling: {
+        /** Why upscaling does not work; `null` while it does. */
+        reason: UpscalingReason | null;
+        /** Whether this plugin has upscaling on (`set`); a test may preset it. */
+        enabled: boolean;
+        /** The factor the player would request; `null` or at most 1: the video needs no upscaling. */
+        factor: number | null;
+        /** Whether the plugin made the player check the GPU (`state`, `set(true)`). */
+        checked: boolean;
+        /** GPU rendering is still starting: a `rendering` reason then lets `set(true)` keep the request. */
+        renderingStarting: boolean;
+    };
     /** What `player.chapters()` lists while media is ready. */
     chapters: {
         /** The chapter title, `null` without one. */