@vestra-player/sdk 1.5.36 → 1.5.38

package/dist/wire.js

@@ -138,6 +138,11 @@ export function createWire(transport) {
             /** The GPU renderer's options (`plugin.video.render()`). */
             renderSet: (values) => transport.request("video.render.set", { values }),
             renderRelease: () => transport.request("video.render.release"),
+            /** The GPU's video upscaler (`plugin.video.upscaling`, player 0.5.16). */
+            upscalingState: () => transport.request("video.upscaling.state"),
+            upscalingSet: (enabled) => transport.request("video.upscaling.set", {
+                enabled,
+            }),
         },
         /** Mark layers on the seek bar (`plugin.timeline`). */
         timeline: {
@@ -250,14 +255,18 @@ export function createWire(transport) {
             set: (options) => transport.request("layout.set", options),
         },
         events: {
-            /** One `events.subscribe` per name however many listeners. */
-            async subscribe(event, listener) {
+            /**
+             * One `events.subscribe` per name however many listeners. `mirror`:
+             * only the SDK keeps a copy of the state (player 0.5.18; older
+             * players ignore it); `listen` changes it.
+             */
+            async subscribe(event, listener, mirror = false) {
                 const off = transport.on(event, listener);
                 let subscription = subscriptions.get(event);
                 if (!subscription) {
                     subscription = {
                         count: 0,
-                        ready: transport.request("events.subscribe", { event }),
+                        ready: transport.request("events.subscribe", mirror ? { event, mirror: true } : { event }),
                     };
                     subscriptions.set(event, subscription);
                 }
@@ -282,6 +291,13 @@ export function createWire(transport) {
                     }
                 };
             },
+            /**
+             * Tell the player whether a subscribed event has a real listener
+             * (`active`) or only the SDK's copy of the state: `events.subscribe`
+             * again, which replaces the mark (player 0.5.18; older players keep
+             * one subscription per name and ignore the mark).
+             */
+            listen: (event, active) => transport.request("events.subscribe", active ? { event } : { event, mirror: true }),
         },
         ui: {
             /** Player 0.2.0: the remote images a Markdown document shows. */

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.36: full reference
+# @vestra-player/sdk 1.5.38: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -329,11 +329,11 @@ The rule that follows: **state you change outside a handler, or after an `await`
 
 #### Stopping
 
-The player stops a plugin when the user disables or uninstalls it, when it is reloaded or upgraded, and when the player quits.
+The player stops a plugin when the user disables or uninstalls it, when it is reloaded or upgraded, when the player quits, and, with lazy activation, when nothing has used it for a while (Idle plugins).
 
 1. The player first removes everything the plugin owns on its side: menu items, windows, panels, settings pages, filter chains, subtitle layers, snapshots, export jobs, resolvers, generated streams.
 2. The SDK then refuses new requests, fails pending ones with `code: "disabled"` and disposes the root scope. That disposal only cleans up locally (timers, abort signals, sockets): the player-side resources are already gone.
-3. A process that has not exited 300 ms later is killed.
+3. A process that has not exited 300 ms later is killed (2 s later when it stops because it is idle).
 
 So `onDispose` cleanup must be quick and must not rely on the player. Media the plugin opened with player.open **keeps playing** after it stops.
 
@@ -344,7 +344,7 @@ A plugin's process does not live as long as the player. Within one player sessio
 - the plugin is **reloaded** (from the plugin manager, or a development load with `--plugin`) or **upgraded**;
 - it **crashed**, or failed to start, and is started again.
 
-A later player may restart a plugin in more cases: restarting plugins that share one process together when one of them faults or hangs, or stopping a plugin nobody uses and starting it on its next use. Write the plugin for those too.
+A later player may restart a plugin in more cases: restarting plugins that share one process together when one of them faults or hangs, or stopping a plugin nobody uses and starting it on its next use (Idle plugins). Write the plugin for those too.
 
 Everything in the process is gone after such a restart: variables, timers, caches, open sockets. The menus, windows and panels come back because `activate` creates them again. **Keep state that must survive a restart in session storage (or persistent storage):**
 
@@ -358,6 +358,16 @@ Session storage is for state that belongs to this run of the player: a queue the
 
 Write `activate` so that running it twice in one session is normal: read what you kept, then build the interface from it.
 
+#### Idle plugins are stopped
+
+With lazy activation (player 0.5.18 and later, while the player turns it on), the player works like a browser's extension service workers (Chrome Manifest V3): a plugin that holds nothing only its process can serve is stopped after about a minute without use, and started again by its next use.
+
+- **What stays while it is stopped**: its menu items and keys (with the last `enabled`, `checked` and `reason` it set), its settings pages, its file and link resolvers and its drop targets. Using one of them, or showing one of its settings pages, starts the plugin; it runs `activate`, registers them again, and then receives the click, the open or the drop. The player also remembers these between runs, so a plugin nobody uses is not started at launch at all.
+- **What keeps it running**: anything the player must deliver to it or that is its running work: a listener (`player.onChange`, `window.onChange`, `bindings.onChange`, `packages.onChange` and the other `onChange`, `onEnd`), a command state, panel or window binding that reads `plugin.player.state` or another state, an open window, a mounted panel, an OSD panel, a timeline layer, a filter chain, a stream or subtitle track it added, a next/previous provider, a sleep lease, a window setting, a job or snapshot in progress. Reading `plugin.player.state` inside a handler does not: the SDK reads the state again when the plugin starts.
+- **What does not keep it running**: work the player does not see. A `fetch`, a socket, a `setTimeout` or `setInterval`, or a promise the plugin awaits is lost when an idle plugin is stopped, as in Chrome. Set the command's `busy` while its work runs (a busy command keeps the plugin running), or keep what it needs in session storage and pick it up in `activate`.
+
+`TestHost.listening` lists the events a plugin really listens to; empty means listeners do not keep it running.
+
 #### The data directory
 
 plugin.dataDirectory is a writable directory for the plugin's own files (settings, caches, remembered folders). It needs no capability; the player creates it before it starts the plugin.
@@ -743,6 +753,14 @@ plugin.video.render() returns the RenderOptions of the GPU renderer: HDR to SDR
 - **Only the GPU renderer has them.** Under software rendering every `set` fails with `unsupported`; see Reference: platforms for where the player renders on the GPU. Treat `unsupported` as "hide these settings", not as an error. To know before creating the handle, read rendering from `plugin.app.system()` (player 0.5.12, no capability): `"gpu"` or `"software"`.
 - A shader that does not compile is reported later: the status first becomes `applied`, then `failed` with code `failed` and the compiler's first error line once mpv first uses the shader.
 
+#### The GPU's video upscaler
+
+plugin.video.upscaling (capability `video.upscaling`, player 0.5.16) turns on the GPU's AI upscaler, NVIDIA RTX Video Super Resolution on Windows. It is not a handle: `set(true)` is the plugin's request, and the player keeps the upscaler last in the filter chain, after every plugin's chain, while any plugin has it on and it can work, scaled to the area the video is shown in. Like render options it acts at display time only.
+
+- **Ask when needed.** The player checks the GPU at the first `state()` or `set(true)` and keeps the answer; the check wakes a sleeping discrete GPU, so ask on the first pick of the item, not while the plugin starts. `set(false)` never checks.
+- **It needs GPU rendering on the upscaler's GPU, with the video decoded there.** A filter chain that needs the frames in memory switches decoding to copy-back, and the upscaler waits (`decoding`) until it is gone.
+- **No sign that it runs.** `requested` says the player asked the driver; on Windows the user must also turn on Super Resolution in the NVIDIA app, which no program can read.
+
 ## Concept: Windows, panels, settings pages, dialogs and the OSD
 
 A plugin can show its own user interface in five places. Three of them are drawn by the plugin's own Slint files: **tool windows**, **panels** and **settings pages**. Two are drawn by the player or the system from plain values: **dialogs** and the **on-screen display (OSD)**. This page explains what each one is, how to choose, how each one lives and dies, how Slint and TypeScript talk to each other, and what to watch out for.
@@ -2690,6 +2708,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.10 | CommandButton, CommandOptions.button |
 | 0.5.12 | SystemInfo.rendering |
 | 0.5.13 | SystemInfo.renderingReason, RenderingMode, RenderingPreference, RenderingReasonCode, RenderingReason, RenderingState, Rendering |
+| 0.5.16 | UpscalingReasonCode, UpscalingReason, UpscalingState, VideoUpscaling |
 
 The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
 
@@ -2727,6 +2746,7 @@ A plugin lists what it may do in the manifest's `capabilities` (Manifest). A cal
 | `ui.theme` | Appearance.set, Appearance.setLanguage | — | Change the player's palette |  |
 | `secrets` | Secrets.get, Secrets.set, Secrets.delete | — | Store sign-in details in the system keychain | yes |
 | `rendering.manage` | Rendering.setPreference, Rendering.restartPlayer | — | Choose GPU or software rendering and restart the player | yes |
+| `video.upscaling` | VideoUpscaling.state, VideoUpscaling.set | — | Upscale the video with the GPU's video upscaler |  |
 
 **Also needs** applies to every member of the row: declare those capabilities as well. A few members or options need one more, documented at the member:
 
@@ -3390,6 +3410,7 @@ A plugin uses the same API on macOS and Windows; the player does the system-spec
 | Rendering | On the GPU (OpenGL), with hardware decoding. | In software, with hardware decoding copied back (`d3d11va-copy` and similar). |
 | plugin.rendering (player 0.5.13) | `"gpu"` can be chosen unless the driver is ruled out (`denylist`, `previous-crash`). | `gpu.available` is `false` (`no-gpu-backend`); `setPreference("gpu")` fails with `unsupported`. |
 | Render options (RenderOptions) | Available; `peakDetect` has no effect. | `unsupported` (software rendering). |
+| plugin.video.upscaling (player 0.5.16) | `available` is `false` (`platform`); `set(true)` fails with `unsupported`. | NVIDIA RTX Video Super Resolution: an RTX GPU with driver 530 or newer, GPU rendering on that GPU, the video decoded on it (`d3d11va`); the user must also turn on Super Resolution in the NVIDIA app, which no program can read. |
 | Bindings | `Ctrl` also matches ⌘; `Cmd` is ⌘. | `Cmd` is the Windows logo key; `Cmd+Q` does not quit. |
 | Keys taken first, standard close keys | See Keys the system takes first. | See Keys the system takes first. |
 | Interface font | The system font; CJK falls back per character to the system's fonts (PingFang, Hiragino). | The system font; CJK falls back per character to Windows' CJK fonts in the interface language's order, then the bundled Noto Sans CJK SC (the chain). |
@@ -3868,7 +3889,7 @@ interface Scope extends Disposable {
   /** Playback state and controls (`playback.read`, `events`, `playback.control`). */
   readonly player: Player;
   /**
-   * Video processing: this plugin's filter chain, the display layer and the GPU render options. All three need `processing.video` and `playback.read`; the filter chain also needs `events` (without it the SDK never sees the media become ready and the chain stays `waiting`).
+   * Video processing: this plugin's filter chain, the display layer, the GPU render options and the GPU's video upscaler. The first three need `processing.video` and `playback.read`; the filter chain also needs `events` (without it the SDK never sees the media become ready and the chain stays `waiting`). The upscaler needs `video.upscaling` only.
    */
   readonly video: {
     /**
@@ -3889,6 +3910,10 @@ interface Scope extends Disposable {
      * @throws Error without a code (throws) A second call in the same plugin while the first handle is not disposed.
      */
     render(): RenderOptions;
+    /**
+     * The GPU's video upscaler (NVIDIA RTX Video Super Resolution on Windows; needs `video.upscaling`, player 0.5.16): whether it works here and why not, and turning it on or off for this plugin.
+     */
+    readonly upscaling: VideoUpscaling;
   };
   /** Audio processing: this plugin's filter chain and delay (`processing.audio`, `playback.read` and `events`, as for VideoFilter). */
   readonly audio: {
@@ -9405,6 +9430,251 @@ render.onStatus((s) => {
 render.set({ toneMapping: "bt.2390", targetPeak: 250 }); // nits
 ```
 
+### UpscalingReasonCode
+
+Why the GPU's video upscaler does not work, as a stable kebab-case code.
+A newer player may add codes: compare with the ones you handle and show
+UpscalingReason.message for the rest. The codes of player 0.5.16,
+in the order the player checks them (the first that holds is reported):
+
+| Code | Meaning |
+| --- | --- |
+| `platform` | The player has no video upscaler on this system (macOS, Linux). |
+| `no-gpu` | No GPU that can upscale video (Windows: no NVIDIA GPU). |
+| `driver` | The graphics driver is too old (Windows: an NVIDIA driver before 530). |
+| `gpu-unsupported` | The driver does not offer upscaling on this GPU (Windows: not an RTX GPU), or the check failed. |
+| `rendering` | The player renders in software, or GPU rendering is still starting; upscaling needs GPU rendering (Rendering). |
+| `adapter` | GPU rendering runs on another GPU than the one that can upscale (a laptop with two GPUs; Windows: choose the high-performance GPU for Vestra in Settings ▸ System ▸ Display ▸ Graphics). |
+| `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a VideoFilter needs the frames in memory. |
+| `unchecked` | The player has not checked the GPU yet. Only in the answer to `set(false)`, which never starts the check; `state()` and `set(true)` always check first. |
+
+`decoding` and `rendering` while GPU rendering is still starting can pass
+during the run, so `set(true)` accepts them and keeps the request; every
+other reason holds until the player restarts, and `set(true)` rejects it.
+Turning upscaling off is always accepted.
+
+- @player 0.5.16
+
+```ts
+type UpscalingReasonCode = "platform" | "no-gpu" | "driver" | "gpu-unsupported" | "rendering" | "adapter" | "decoding" | "unchecked" | (string & {});
+```
+
+Example: Advise the user by reason
+
+The plugin shows its own advice for the reasons the user can act on and
+the player's message for the rest. `reason.code` is looked up among the
+codes the plugin knows; an unknown code from a newer player falls
+through to the message, which names the GPU and what to do.
+```ts
+const { reason } = await plugin.video.upscaling.state();
+// Advice for the codes this plugin knows; any other code shows the message.
+const advice: Partial<Record<UpscalingReasonCode, string>> = {
+  driver: "Update the NVIDIA driver to 530 or newer.",
+  rendering: "Turn on Video ▸ GPU Rendering (Experimental) and restart.",
+};
+if (reason) console.log(advice[reason.code] ?? reason.message);
+```
+
+### UpscalingReason
+
+Why the GPU's video upscaler does not work: a stable
+UpscalingReasonCode to branch on and a sentence to show, the same
+shape as RenderingReason.
+
+- @player 0.5.16
+
+```ts
+interface UpscalingReason {
+  /** The reason as a stable kebab-case code; branch on this. */
+  readonly code: UpscalingReasonCode;
+  /** The reason as English text for people, for example with the GPU's name and what to change; never branch on it. */
+  readonly message: string;
+}
+```
+
+Example: Grey out a menu item with the player's reason
+
+The plugin disables its upscaling item and shows why. `message` is the
+player's English text, naming the GPU and what the user can do (turn on
+GPU rendering, choose the other GPU, update the driver); `code` is for
+decisions.
+```ts
+const { available, reason } = await plugin.video.upscaling.state();
+if (!available && reason) console.log(`${reason.code}: ${reason.message}`);
+```
+
+### UpscalingState
+
+What VideoUpscaling.state and VideoUpscaling.set report:
+whether the upscaler works now and why not, whether this plugin turned
+it on, and whether the player asked the GPU to upscale.
+
+`requested` is as far as the player can see. The player puts the
+upscaler last in the video filter chain, scaling the video to the area it
+is shown in; the driver gives no sign that it upscales. On Windows the
+user must also turn on Super Resolution in the NVIDIA app (System ▸ Video
+▸ RTX Video Enhancement), which no program can read: say so next to the
+switch.
+
+- @player 0.5.16
+
+```ts
+interface UpscalingState {
+  /** Whether the upscaler works now; `false` with UpscalingState.reason. */
+  readonly available: boolean;
+  /** Why it does not work now; `null` while it does. */
+  readonly reason: UpscalingReason | null;
+  /** This plugin asked for upscaling (VideoUpscaling.set) and has not turned it off. */
+  readonly enabled: boolean;
+  /**
+   * The player has the upscaler in the video filter chain now, for this plugin or another one: upscaling is enabled and available and the video is shown larger than its own size. Not a sign that the GPU upscales (see the remarks).
+   */
+  readonly requested: boolean;
+  /**
+   * The scale factor the upscaler was asked for (the area the video is shown in over the video's size, in hundredths, above 1); `null` while nothing is requested.
+   */
+  readonly factor: number | null;
+}
+```
+
+Example: Label the item with what happens now
+
+The plugin's menu item says whether upscaling is on and whether the
+video is being upscaled. `enabled` is this plugin's own request;
+`requested` is true while the player has the upscaler in the filter
+chain, which needs a video shown larger than its own size (`factor`
+above 1).
+```ts
+const state = await plugin.video.upscaling.state();
+// `enabled`: this plugin's request; `requested`: in the filter chain now.
+const label = !state.enabled
+  ? "AI Upscaling: Off"
+  : state.requested
+    ? `AI Upscaling: On (×${state.factor?.toFixed(2)})`
+    : "AI Upscaling: On (not needed for this video)";
+console.log(label);
+```
+
+### VideoUpscaling
+
+`plugin.video.upscaling`: the GPU's video upscaler, NVIDIA RTX Video
+Super Resolution on Windows (`video.upscaling`). Read whether it works
+here and why not; turn it on or off for this plugin.
+
+The player checks the GPU once, when a plugin first asks, and keeps the
+answer: the check wakes a sleeping discrete GPU, so call
+VideoUpscaling.state when the plugin first needs the answer (the
+first time the user picks its upscaling item), not while the plugin
+starts, and do not poll it. `set(false)` never starts the check. It works
+only with GPU rendering, on the GPU the upscaler runs on, with the video decoded on that GPU; UpscalingReasonCode
+lists what can stand in the way.
+
+While some plugin has it on and it works, the player puts the upscaler
+last in the video filter chain and scales the video to the area it is
+shown in, following window and video size changes (a resize waits until
+the size holds). A video already shown at its own size or smaller is not
+upscaled. The upscaler stays while any plugin has it on; it goes when the
+last one turns it off or stops: the player revokes a stopped plugin's
+request.
+
+**Windows:** the user must turn on Super Resolution in the NVIDIA app
+(System ▸ Video ▸ RTX Video Enhancement); no program can read that
+switch, and the driver gives no sign that it upscales
+(UpscalingState.requested is as far as the player can see). It
+uses the NVIDIA GPU, so power use and heat go up, and on a laptop with
+two GPUs the whole player must run on the NVIDIA one.
+**macOS, Linux:** `available` is `false` with `platform`.
+
+Players before 0.5.16 do not know `video.upscaling` and do not load a
+plugin that declares it: declare `"minPlayerVersion": "0.5.16"`.
+
+- @capability video.upscaling
+- @player 0.5.16; older players do not load a plugin that declares `video.upscaling`.
+
+```ts
+interface VideoUpscaling {
+  /**
+   * Read whether the upscaler works now and why not, whether this plugin turned it on and what the player asked the GPU for.
+   * @capability video.upscaling
+   * @returns The state, once the player's GPU check ran (the first call starts it and may take a moment).
+   * @throws capability (rejects) The manifest does not declare `video.upscaling`.
+   * @example Find out whether upscaling can work here
+   * The plugin reads the state the first time the user picks its upscaling
+   * item and keeps it for the item. The first call makes the player check the GPU (which
+   * wakes a sleeping discrete GPU) and later calls reuse the answer; the
+   * rest (GPU rendering, the GPU it runs on, the decoding) is read at
+   * each call.
+   * ```ts
+   * const { available, reason } = await plugin.video.upscaling.state();
+   * if (!available) console.log(reason?.message);
+   * ```
+   */
+  state(): Promise<UpscalingState>;
+  /**
+   * Turn upscaling on or off for this plugin.
+   *
+   * On stays this plugin's request until it turns it off or stops; the
+   * player upscales whenever the request can take effect (a `decoding`
+   * reason can pass with the next file). Off takes the upscaler out at
+   * once unless another plugin has it on. Upscaling is a request of the
+   * whole plugin, not of a Scope: disposing a scope does not turn
+   * it off.
+   * @capability video.upscaling
+   * @param enabled - `true` to ask for upscaling, `false` to withdraw the request.
+   * @returns The new state.
+   * @throws capability (rejects) The manifest does not declare `video.upscaling`.
+   * @throws invalid (rejects) `enabled` is not a boolean.
+   * @throws unsupported (rejects) `true` where upscaling cannot work in this run: every UpscalingReasonCode except `decoding`, and except `rendering` while GPU rendering is still starting (those two are accepted and the request is kept until they pass); `message` is the reason. Nothing changes. `false` is always accepted and answered at once without the GPU check (before any check, `available` is `false` with `unchecked`).
+   * @example Turn upscaling on and explain what is needed
+   * The plugin turns upscaling on from its settings and tells the user what
+   * else to switch on. `set(true)` records the request and resolves with the
+   * new state; where upscaling cannot work in this run it rejects with
+   * `unsupported` and the player's reason instead.
+   * ```ts
+   * try {
+   *   const state = await plugin.video.upscaling.set(true);
+   *   // The driver's own switch cannot be read: remind the user once.
+   *   if (state.enabled) await plugin.osd.show("Turn on Super Resolution in the NVIDIA app");
+   * } catch (error) {
+   *   if ((error as PluginError).code !== "unsupported") throw error;
+   *   await plugin.osd.show("AI upscaling: {}", [(error as PluginError).message]);
+   * }
+   * ```
+   */
+  set(enabled: boolean): Promise<UpscalingState>;
+}
+```
+
+Example: Offer AI upscaling as a menu item
+
+A Video menu item turns upscaling on and off; once the player said it
+cannot work here, the item is greyed out with the player's reason. The
+state is read the first time the user picks the item (that runs the
+player's GPU check, so nothing wakes the GPU while the plugin starts) and
+again after each pick; `set` resolves with the new state, or rejects with
+`unsupported` where upscaling cannot work in this run.
+```ts
+let state: UpscalingState | null = null; // unknown until first picked
+plugin.commands.add({
+  id: "upscaling",
+  path: ["@video", "AI Upscaling"],
+  checked: () => state?.enabled ?? false,
+  // Greyed only once the player said it cannot work (`decoding` can pass).
+  enabled: () => state === null || state.available || state.reason?.code === "decoding",
+  reason: () => state?.reason?.message ?? null, // shown while disabled
+  run: async () => {
+    state ??= await plugin.video.upscaling.state(); // the first pick checks the GPU
+    try {
+      state = await plugin.video.upscaling.set(!(state?.enabled ?? false));
+    } catch (error) {
+      // Cannot work in this run (no RTX GPU, software rendering…).
+      if ((error as PluginError).code !== "unsupported") throw error;
+      state = await plugin.video.upscaling.state();
+    }
+  },
+});
+```
+
 ### SubtitleTrack
 
 A subtitle track of the current source.
@@ -10475,6 +10745,10 @@ interface PluginInfo {
    * The manifest's display texts in the interface language, translated with that package's catalog; absent from players before 0.4.3 (read `manifest.json` there).
    */
   display?: PluginDisplay;
+  /**
+   * For `state: "running"`: `"running"` while its process runs, `"idle"` while the player stopped it because nothing used it (lazy activation: it starts again on its next use, its menu items, keys, settings pages, resolvers and drop targets stay). Absent in other states and from players before 0.5.18. A change between the two alone does not fire Packages.onChange.
+   */
+  process?: "running" | "idle";
 }
 ```
 
@@ -12504,7 +12778,8 @@ Members fall into a few groups:
   TestHost.app, TestHost.systemInfo,
   TestHost.chapters, TestHost.audioDevices,
   TestHost.secrets, TestHost.clipboard,
-  TestHost.tools, TestHost.rendering.
+  TestHost.tools, TestHost.rendering,
+  TestHost.upscaling.
 - **Assert** on records: TestHost.osd, TestHost.calls,
   TestHost.sent, TestHost.conflicts,
   TestHost.layout, TestHost.menus, and many more.
@@ -12535,6 +12810,10 @@ 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…).
+   */
+  readonly listening: Set<string>;
   /**
    * The player's source facts (phase, position, duration, paused, rate, audio tracks, loop, ...). Wire-level shape; change it with TestHost.setSource, which also broadcasts it.
    */
@@ -13407,6 +13686,62 @@ 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();
+   * ```
+   */
+  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. */

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.36: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
+> @vestra-player/sdk 1.5.38: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
 
 **Rules**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2628–2697.
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2646–2716.
 
 **main.ts**
 
@@ -77,9 +77,10 @@ export default async function activate(plugin: Plugin) {
 - `ui.theme`: Appearance.set/setLanguage
 - `secrets`: Secrets.get/set/delete
 - `rendering.manage`: Rendering.setPreference/restartPlayer
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2698–2757.
+- `video.upscaling`: VideoUpscaling.state/set
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2717–2777.
 
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L2069–2257; TestHost: L12484.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L2087–2275; TestHost: L12758.
 
 **Command line**
 
@@ -107,39 +108,39 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player
-- Others: PluginError, llms-full.txt L3759.
+- Others: PluginError, llms-full.txt L3780.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; pages: [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–237
-- Concepts: How a plugin runs L238–408; Commands, menus and key bindings L409–520; Playback state, controls and sources L521–666; Video and audio processing L667–745; Windows, panels, settings pages, dialogs and the OSD L746–1034
-- How-to: Control playback L1035–1163; Store a plugin's data L1164–1231; Load subtitles from a plugin L1232–1310; Keep a slider responsive while dragging L1311–1485; Remember a window's state between runs L1486–1615; Offer a GPU rendering switch L1616–1736; Translate a plugin L1737–1920; Migrate a plugin to English source text L1921–2068; Test a plugin L2069–2257; Publish a plugin L2258–2346; Migrating off package rollback (1.5.16, removed in 1.5.17) L2347–2422
-- Guidelines: Interface guidelines L2423–2530; Menu guidelines L2531–2627
-- Reference: Manifest L2628–2697; Capabilities L2698–2757; Limits L2758–2887; Commands, menus and bindings L2888–3371; Platforms L3372–3401; Theme L3402–3623; Command line L3624–3681
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3682–12168
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12169–14827
+- Concepts: How a plugin runs L238–418; Commands, menus and key bindings L419–530; Playback state, controls and sources L531–676; Video and audio processing L677–763; Windows, panels, settings pages, dialogs and the OSD L764–1052
+- How-to: Control playback L1053–1181; Store a plugin's data L1182–1249; Load subtitles from a plugin L1250–1328; Keep a slider responsive while dragging L1329–1503; Remember a window's state between runs L1504–1633; Offer a GPU rendering switch L1634–1754; Translate a plugin L1755–1938; Migrate a plugin to English source text L1939–2086; Test a plugin L2087–2275; Publish a plugin L2276–2364; Migrating off package rollback (1.5.16, removed in 1.5.17) L2365–2440
+- Guidelines: Interface guidelines L2441–2548; Menu guidelines L2549–2645
+- Reference: Manifest L2646–2716; Capabilities L2717–2777; Limits L2778–2907; Commands, menus and bindings L2908–3391; Platforms L3392–3422; Theme L3423–3644; Command line L3645–3702
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3703–12442
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12443–15162
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L4081, Scope L3834, PluginError L3759, Disposable L3697
-- Commands L4478; Windows L5415; Panels L6861; Dialogs L7529; Player L8270; video: VideoFilter L9150, VideoView L9250, RenderOptions L9337; audio: AudioFilter L9195; Subtitles L9484; media: MediaCapture L9888; Resolvers L10118; Packages L10516; Osd L9015; Host L8857; Clipboard L10844; Power L10931; Tools L10990; Storage L11142; System L11341; Secrets L11421; window: MainWindow L7178; App L7358; Rendering L11684; Bindings L10744; Ui L4767; Timeline L7090; Drops L6108; Appearance L6189; I18n L6422; Settings L6705.
+- Plugin L4106, Scope L3855, PluginError L3780, Disposable L3718
+- Commands L4503; Windows L5440; Panels L6886; Dialogs L7554; Player L8295; video: VideoFilter L9175, VideoView L9275, RenderOptions L9362, VideoUpscaling L9558; audio: AudioFilter L9220; Subtitles L9754; media: MediaCapture L10158; Resolvers L10388; Packages L10790; Osd L9040; Host L8882; Clipboard L11118; Power L11205; Tools L11264; Storage L11416; System L11615; Secrets L11695; window: MainWindow L7203; App L7383; Rendering L11958; Bindings L11018; Ui L4792; Timeline L7115; Drops L6133; Appearance L6214; I18n L6447; Settings L6730.
 
 ## Examples
 
 Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L15262–15351
-- blur: A tool window with one slider that blurs the playing video. L15352–15613
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L15614–15946
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L15947–16133
-- panel-menu: A sidebar panel with its own right-click menu. L16134–16342
-- menus: Radio menu items, separator groups and a menu item whose title changes. L16343–16502
-- theme-widgets: A tool window drawn with the player's theme and widgets. L16503–16666
-- markdown: A window that shows a Markdown document. L16667–16863
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L16864–17031
+- hello: The README Quick start: one menu command and an on-screen message. L15597–15686
+- blur: A tool window with one slider that blurs the playing video. L15687–15948
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L15949–16281
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L16282–16468
+- panel-menu: A sidebar panel with its own right-click menu. L16469–16677
+- menus: Radio menu items, separator groups and a menu item whose title changes. L16678–16837
+- theme-widgets: A tool window drawn with the player's theme and widgets. L16838–17001
+- markdown: A window that shows a Markdown document. L17002–17198
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L17199–17366
 
 ## Optional
 

package/package.json

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