@vestra-player/sdk 1.5.41 → 1.5.43

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.5.43
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`, no new capability. The new API needs player 0.5.25 (`"minPlayerVersion": "0.5.25"`); older players leave the new fields out and refuse the new event (the listener never fires). The `decoding` reason code stays as it is: the cause is a new optional field beside it.
+
+- **`UpscalingReason.cause`** (player 0.5.25): with code `decoding`, why the video is not decoded on the GPU that renders it, as a stable `UpscalingDecodingCause`: `copy-back` (decoded on the GPU and copied back to memory, usually because a plugin's video filter needs the frames there), `hwdec-off` (hardware decoding off), `software` (this video is decoded in software: a cover picture, an unsupported format), `other-hwdec` (another hardware decoder). A newer player may add causes. With `copy-back`, **`UpscalingReason.plugins`** lists whose video filters made the player switch (`UpscalingPlugin`: manifest `id` and `name`; empty when the copy-back mode is the user's own setting), and the message names them ("…because the video filter of Picture Adjustments needs the frames in memory").
+- **Monitoring fields in `UpscalingState`** (player 0.5.25, optional: absent from older players): `video` (the video's stored and display size as the upscaler gets it, `UpscalingVideoSize`), `area` (the video area in pixels), `gpu` (the rendering GPU's name), `hwdecCurrent` (mpv's decoder for this video), `inChain` (the upscaler is in the filter chain now, read from the chain). The driver still gives no sign that it upscales.
+- **`plugin.video.upscaling.onChange(listener)`** (player 0.5.25, `video.upscaling`): the state whenever it changes while some plugin has upscaling on (the player looks about five times a second and sends only differences), so a window can show it live without polling. Wire: event `video.upscaling.changed` with the state without `enabled` (the SDK adds this plugin's own); subscribing needs `video.upscaling`, not `events`. A listener keeps the plugin running (it is not an event the player wakes a stopped plugin for): listen only while a window shows the state. The manifest names in `plugins` and the message are not translated.
+- **`TestHost`**: `upscalingDecoding(cause, plugins?)` fakes each cause with the player's message (and a matching `upscaling.hwdecCurrent`); `upscaling.video`, `area`, `gpu`, `hwdecCurrent` (defaults: 1080p on a 4K area, an RTX 4070, `d3d11va`; `inChain` follows `requested`); `upscalingChanged()` sends the event to a listening plugin.
+- The player's capability table copy (`video.upscaling.changed` under `video.upscaling`) and `CAPABILITY_INFO` (`VideoUpscaling.onChange`) follow.
+
+
+## 1.5.42
+
+**Who must change: nobody.** Documentation only: no API changes, `apiVersion` stays `vestra/1`, no player version needed. The package's code is the same as 1.5.41; the doc comments' `@see` links (27 in `src/plugin/types.ts`) now point at `docs/explanation/` instead of `docs/concepts/`. The site's page addresses stay the same, and the old _Concepts_ group address redirects to _Explanation_; `llms.txt` and `llms-full.txt` follow the new pages.
+
+- **The documentation follows Diátaxis.** The site's groups are Tutorials, How-to, Reference, Explanation, Guidelines, Examples and Upgrading, each with one kind of page whose shape `npm run docs:check` enforces (a tutorial has `Before you start`, numbered steps and `Next`; a how-to guide a goal, steps, a complete example and `See also`; explanation pages give no steps). _Concepts_ became _Explanation_ (the old address redirects); the migration notes moved to _Upgrading_ (`docs/upgrading/`), with every release's "who must change" in one generated table. New pages: tutorials _Add a window_, _Add settings and translations_, _Test, check, pack and publish_; _Troubleshooting_; reference pages _Error codes_, _Translations_ and _Test host_ (generated tables); explanation pages _GPU and software rendering_, _The player's Rust core_ and _How the player runs and talks to plugins_. Diagrams are Mermaid, and a check refuses link syntax in their labels.
+- **New tutorial _Write your own blur kernel_**: what the numbers of a 3×3 blur kernel do and why it is normalized; the kernel as an mpv user shader the plugin owns, applied with `plugin.video.shaders()`; the same kernel as a `convolution` node (the 9, 25 and 49 entry sizes, `row` and `column` kernels, `rdiv`, `bias` and `VIDEO_PROCESSING_LIMITS`) that also reaches processed snapshots; and `gblur` as the shortcut.
+- **New how-to guide _Keep a command's state without keeping the plugin running_**: find what keeps a plugin running with `TestHost.keepsRunning`, replace functions that read `plugin.player.state` with `plugin.when` conditions, keep the plugin's own state as values, and test it.
+- _Commands, menus and key bindings_ (explanation) explains `plugin.when`: why the player evaluates conditions, how they relate to idle stop, mirror and listening subscriptions, and `keepsRunning` / `listeningWhy`. _How a plugin runs_ says that listeners of `packages`, `bindings`, `appearance` and the resolvers' file types no longer keep a plugin running (player 0.5.21). _Video and audio processing_ describes the shader channel and the `convolution` and `lut3d` nodes.
+- _The player's Rust core_ shows the current window renderer choice (player 0.5.20): Direct3D 12 windows in CPU mode on Windows and their fallback to software windows. No page says any longer that only macOS renders on the GPU.
+
 ## 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.
@@ -210,7 +231,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 
 ## 1.5.17
 
-**Package rollback is removed**, as announced in 1.5.16: the player keeps no previous plugin version. `apiVersion` stays `vestra/1` (a patch release, as when 1.5.8 removed `PackageCandidate.trial()`); plugins that do not manage other plugins need no change. A plugin manager that still calls `rollback` or reads `previousVersion` no longer compiles. Migration: [Migrating off package rollback](docs/how-to/rollback-migration.md).
+**Package rollback is removed**, as announced in 1.5.16: the player keeps no previous plugin version. `apiVersion` stays `vestra/1` (a patch release, as when 1.5.8 removed `PackageCandidate.trial()`); plugins that do not manage other plugins need no change. A plugin manager that still calls `rollback` or reads `previousVersion` no longer compiles. Migration: [Migrating off package rollback](docs/upgrading/rollback-migration.md).
 
 - **Removed: `Packages.rollback`** and the wire method `packages.rollback`. The player already answers the method with `unsupported` ("unknown package method"). To go back to an older version of a third-party plugin, the user uninstalls it and installs that version's `.vxp`.
 - **Removed: `PluginInfo.previousVersion`** and the wire field `PackageInfo.previousVersion`; `packages.list` and `packages.changed` no longer carry it.
@@ -221,7 +242,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 
 ## 1.5.16
 
-**Package rollback is deprecated: the player keeps no previous plugin version.** `apiVersion` stays `vestra/1`; code still compiles, and plugins that do not manage other plugins need no change. 1.5.17 removes the deprecated symbols, as 1.5.8 removed `PackageCandidate.trial()` at patch level. Migration: [Migrating off package rollback](docs/how-to/rollback-migration.md).
+**Package rollback is deprecated: the player keeps no previous plugin version.** `apiVersion` stays `vestra/1`; code still compiles, and plugins that do not manage other plugins need no change. 1.5.17 removes the deprecated symbols, as 1.5.8 removed `PackageCandidate.trial()` at patch level. Migration: [Migrating off package rollback](docs/upgrading/rollback-migration.md).
 
 - **Deprecated: `Packages.rollback`** (removed in 1.5.17). The player no longer has `packages.rollback` and answers it with `unsupported` ("unknown package method"); the SDK still forwards the call, so the error reaches the caller. To go back to an older version of a third-party plugin, the user uninstalls it and installs that version's `.vxp`.
 - **Deprecated: `PluginInfo.previousVersion`** and the wire field `PackageInfo.previousVersion` (removed in 1.5.17): always `null`, since an upgrade replaces the package. The SDK reads a missing field as `null`.
@@ -299,7 +320,7 @@ Fixes for Windows and for a vendored SDK, and built-ins that can no longer be di
 
 ## 1.5.9
 
-**Translations** (player 0.4.3). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.8 need no change. One test-visible change: a core action's `declaration.path` in `TestHost` is now the player's English key (read `display` for what the menu shows). The player now shows its interface in English, Simplified Chinese, Japanese, Korean, German, French or Spanish, chosen at start-up; a plugin writes every text in English and ships one gettext file per language. Plugins write no translation code: the player translates. Guides: [Translate a plugin](docs/how-to/i18n.md), [Migrate a plugin to English source text](docs/how-to/i18n-migration.md); example: `examples/i18n`.
+**Translations** (player 0.4.3). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.8 need no change. One test-visible change: a core action's `declaration.path` in `TestHost` is now the player's English key (read `display` for what the menu shows). The player now shows its interface in English, Simplified Chinese, Japanese, Korean, German, French or Spanish, chosen at start-up; a plugin writes every text in English and ships one gettext file per language. Plugins write no translation code: the player translates. Guides: [Translate a plugin](docs/how-to/i18n.md), [Migrate a plugin to English source text](docs/upgrading/i18n-migration.md); example: `examples/i18n`.
 
 - **`plugin.i18n.locale`** (new `I18n`, `Locale`): the interface language of this run, `"en"`, `"zh-Hans"`, `"ja"`, `"ko"`, `"de"`, `"fr"` or `"es"`; it never changes while the player runs. `"en"` from older players.
 - **Templates with arguments**: `osd.show(text, args?)`, `OsdPanel.set(text, args?)` and `ConfirmOptions.args` (new `TemplateArgs`: an array for `{}` / `{0}`, an object for `{name}`). The player translates the template with the plugin's catalog, then fills it in. Without `args` the text shows as it is, so existing calls are unchanged; older players show the template unfilled.

package/README.md

@@ -57,7 +57,7 @@ export default async function activate(plugin: Plugin) {
 }
 ```
 
-Run `npx vestra-plugin pack` to check and package it, or start the player with `--plugin <folder>` to try it right away. This is [`examples/hello`](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/hello); [Getting started](https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html) adds a window, tests and packaging.
+Run `npx vestra-plugin pack` to check and package it, or start the player with `--plugin <folder>` to try it right away. This is [`examples/hello`](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/hello); the [Tutorials](https://vestrasys.github.io/vestra-player-sdk/documents/Tutorials.html) build a plugin in four lessons: [Getting started](https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html) (a menu item and an on-screen message), then a window, settings and translations, and tests, packing and publishing.
 
 ## Examples
 
@@ -79,12 +79,13 @@ Complete, tested plugins in [`examples/`](https://github.com/vestrasys/vestra-pl
 
 The [documentation site](https://vestrasys.github.io/vestra-player-sdk/) is the one place for everything a plugin author needs:
 
-- **[Tutorials](https://vestrasys.github.io/vestra-player-sdk/documents/Tutorials.html)**: [Getting started](https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html), from an empty folder to a packed plugin.
-- **[Concepts](https://vestrasys.github.io/vestra-player-sdk/documents/Concepts.html)**: how a plugin runs, commands and key bindings, playback, video and audio processing, the interface.
-- **[How-to guides](https://vestrasys.github.io/vestra-player-sdk/documents/How-to_guides.html)**: testing, translating and publishing a plugin, responsive sliders, remembering window state.
-- **[Guidelines](https://vestrasys.github.io/vestra-player-sdk/documents/Guidelines.html)**: rules for the interface and the menus.
+- **[Tutorials](https://vestrasys.github.io/vestra-player-sdk/documents/Tutorials.html)**: four lessons that build one plugin, starting with [Getting started](https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html): a menu item, a window, settings and translations, tests and the store; then a lesson on writing your own blur kernel (a GPU shader and a convolution node).
+- **[How-to guides](https://vestrasys.github.io/vestra-player-sdk/documents/How-to_guides.html)**: one task each (goal, steps, complete example): playback, storage, subtitles, sliders, window state, the GPU switch, menu state that needs no running plugin (`plugin.when`), translating, testing, publishing; and troubleshooting.
+- **[Reference](https://vestrasys.github.io/vestra-player-sdk/documents/Reference.html)**: capabilities, manifest fields, limits, menus and bindings, platforms, theme, error codes, translations, the test host, and the [command line](https://vestrasys.github.io/vestra-player-sdk/documents/Command_line.html) (`vestra-plugin check`, `test`, `build`, `pack`, `i18n extract`, `i18n check`).
+- **[Explanation](https://vestrasys.github.io/vestra-player-sdk/documents/Explanation.html)**: how a plugin runs, commands and key bindings, playback, video and audio processing, the interface, GPU and software rendering, the player's Rust core and how it runs and talks to plugins.
+- **[Guidelines](https://vestrasys.github.io/vestra-player-sdk/documents/Guidelines.html)**: rules for every plugin, the interface and the menus.
 - **[Examples](https://vestrasys.github.io/vestra-player-sdk/documents/Examples.html)**: the walkthroughs above.
-- **[Reference](https://vestrasys.github.io/vestra-player-sdk/documents/Reference.html)**: capabilities, manifest fields, limits, menus and bindings, platforms, theme, and the [command line](https://vestrasys.github.io/vestra-player-sdk/documents/Command_line.html) (`vestra-plugin check`, `test`, `build`, `pack`, `i18n extract`, `i18n check`).
+- **[Upgrading](https://vestrasys.github.io/vestra-player-sdk/documents/Upgrading.html)**: what to change when a release deprecates or removes something, with the migration checklists and every release's "who must change".
 - **[API](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html)**: every type and member of `@vestra-player/sdk` and `@vestra-player/sdk/testing`.
 
 ## Compatibility

package/dist/api-requests.js

@@ -146,4 +146,5 @@ export const API_REQUESTS = Object.freeze({
     "Rendering.restartPlayer": [{ method: "rendering.restart" }],
     "VideoUpscaling.state": [{ method: "video.upscaling.state" }],
     "VideoUpscaling.set": [{ method: "video.upscaling.set" }],
+    "VideoUpscaling.onChange": [listen("video.upscaling.changed")],
 });

package/dist/host-capabilities.js

@@ -85,6 +85,7 @@ export const HOST_CAPABILITIES = {
                         cases: {
                             "bindings.changed": "bindings.manage",
                             "packages.changed": null,
+                            "video.upscaling.changed": "video.upscaling",
                         },
                         otherwise: "events",
                         param: "event",
@@ -96,6 +97,7 @@ export const HOST_CAPABILITIES = {
                         cases: {
                             "bindings.changed": "bindings.manage",
                             "packages.changed": null,
+                            "video.upscaling.changed": "video.upscaling",
                         },
                         otherwise: "events",
                         param: "event",

package/dist/plugin/services.js

@@ -508,16 +508,38 @@ export const videoUpscaling = (scope) => {
         if (!scope.runtime.can("video.upscaling"))
             throw failure("capability", "video.upscaling must be declared in manifest");
     };
+    // This plugin's own request, kept from every answer for `onChange`: the
+    // event leaves it out (it is each plugin's own), and only this plugin's
+    // `set` changes it.
+    const noted = (state) => {
+        enabledOf.set(scope.runtime, state.enabled);
+        return state;
+    };
     return {
         async state() {
             declared();
-            return (await scope.runtime.host.video.upscalingState());
+            return noted(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));
+            return noted(await scope.runtime.host.video.upscalingSet(enabled));
+        },
+        onChange(listener) {
+            declared();
+            const watch = scope.runtime.on("video.upscaling.changed", (data) => scope.run(listener, {
+                ...data,
+                enabled: enabledOf.get(scope.runtime) ?? false,
+            }), "video.upscaling");
+            return scope.add({
+                dispose: async () => {
+                    scope.forget(watch);
+                    await watch.dispose();
+                },
+            });
         },
     };
 };
+/** Each plugin's own upscaling request, as its last answer said. */
+const enabledOf = new WeakMap();

package/dist/plugin/testing.d.ts

@@ -16,7 +16,7 @@ import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
 import { VIDEO_PROCESSING_LIMITS } from "../processing.ts";
-import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingReason, ViewSettings } from "./types.ts";
+import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingDecodingCause, UpscalingPlugin, UpscalingReason, UpscalingVideoSize, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
 import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
 import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
@@ -1862,7 +1862,71 @@ export declare class TestHost implements Transport {
         checked: boolean;
         /** GPU rendering is still starting: a `rendering` reason then lets `set(true)` keep the request. */
         renderingStarting: boolean;
+        /** The video's size the state reports (player 0.5.25); `null`: no video. */
+        video: UpscalingVideoSize | null;
+        /** The video area the state reports (player 0.5.25); `null`: none. */
+        area: {
+            /** Width in physical pixels. */
+            width: number;
+            /** Height in physical pixels. */
+            height: number;
+        } | null;
+        /** The rendering GPU's name the state reports (player 0.5.25). */
+        gpu: string | null;
+        /** mpv's decoder the state reports (player 0.5.25); `null`: no video. */
+        hwdecCurrent: string | null;
     };
+    /**
+     * Make the upscaler's reason `decoding` with `cause`, with the player's
+     * message (player 0.5.25), and set `upscaling.hwdecCurrent` to match
+     * (`d3d11va-copy`, `no`, `nvdec`). `plugins` are named for `copy-back`
+     * only, as the player does. Returns the reason; call
+     * {@link TestHost.upscalingChanged} to tell a listening plugin.
+     *
+     * @example Test the window's advice for each cause
+     * The plugin's window explains why upscaling waits. The test fakes the
+     * copy-back cause that Picture Adjustments' filters cause and checks
+     * that the window names the plugin.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscalingDecoding("copy-back", [{ id: "vestra.video", name: "Picture Adjustments" }]);
+     * host.upscalingChanged();
+     * await host.settle();
+     * assert.match(String(host.window("upscale").props.blocker), /Picture Adjustments/);
+     * ```
+     *
+     * @capability None.
+     * @since 1.5.43
+     */
+    upscalingDecoding(cause: UpscalingDecodingCause, plugins?: readonly UpscalingPlugin[]): UpscalingReason;
+    /**
+     * Send `video.upscaling.changed` with the state {@link TestHost.upscaling}
+     * describes now (without `enabled`), as the player does when it changes
+     * (player 0.5.25); a plugin listening with
+     * `plugin.video.upscaling.onChange` receives it. Nothing reaches a plugin
+     * that does not listen.
+     *
+     * @capability None.
+     *
+     * @example Show the new factor in the plugin's window
+     * The window resized: the test changes the area and the factor, sends
+     * the change, and checks that the plugin's window shows the new factor.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscaling.area = { width: 2560, height: 1440 };
+     * host.upscaling.factor = 1.33; // 1080p in a 1440p area
+     * host.upscalingChanged(); // as the player after the resize settled
+     * await host.settle();
+     * assert.equal(host.window("upscale").props.factor, "×1.33");
+     * ```
+     *
+     * @since 1.5.43
+     */
+    upscalingChanged(): void;
     /** What `player.chapters()` lists while media is ready. */
     chapters: {
         /** The chapter title, `null` without one. */

package/dist/plugin/testing.js

@@ -1837,7 +1837,104 @@ export class TestHost {
         factor: 2,
         checked: false,
         renderingStarting: false,
+        video: {
+            width: 1920,
+            height: 1080,
+            displayWidth: 1920,
+            displayHeight: 1080,
+        },
+        area: { width: 3840, height: 2160 },
+        gpu: "NVIDIA GeForce RTX 4070 Laptop GPU",
+        hwdecCurrent: "d3d11va",
     };
+    /**
+     * Make the upscaler's reason `decoding` with `cause`, with the player's
+     * message (player 0.5.25), and set `upscaling.hwdecCurrent` to match
+     * (`d3d11va-copy`, `no`, `nvdec`). `plugins` are named for `copy-back`
+     * only, as the player does. Returns the reason; call
+     * {@link TestHost.upscalingChanged} to tell a listening plugin.
+     *
+     * @example Test the window's advice for each cause
+     * The plugin's window explains why upscaling waits. The test fakes the
+     * copy-back cause that Picture Adjustments' filters cause and checks
+     * that the window names the plugin.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscalingDecoding("copy-back", [{ id: "vestra.video", name: "Picture Adjustments" }]);
+     * host.upscalingChanged();
+     * await host.settle();
+     * assert.match(String(host.window("upscale").props.blocker), /Picture Adjustments/);
+     * ```
+     *
+     * @capability None.
+     * @since 1.5.43
+     */
+    upscalingDecoding(cause, plugins = []) {
+        const needs = "upscaling needs it decoded on the GPU that renders it (d3d11va)";
+        const names = plugins.map((p) => p.name);
+        const because = names.length === 0
+            ? "for example because a video filter needs the frames in memory"
+            : names.length === 1
+                ? `because the video filter of ${names[0]} needs the frames in memory`
+                : `because the video filters of ${names.join(", ")} need the frames in memory`;
+        const [message, current] = cause === "copy-back"
+            ? [
+                `the video is decoded with copy-back (auto-copy-safe), ${because}; ${needs}`,
+                "d3d11va-copy",
+            ]
+            : cause === "hwdec-off"
+                ? [
+                    "hardware decoding is off; upscaling needs the video decoded on the GPU that renders it (d3d11va)",
+                    "no",
+                ]
+                : cause === "software"
+                    ? [`this video is decoded in software; ${needs}`, "no"]
+                    : [`this video is decoded with nvdec; ${needs}`, "nvdec"];
+        const reason = cause === "copy-back"
+            ? {
+                code: "decoding",
+                message,
+                cause,
+                plugins: plugins.map(({ id, name }) => ({ id, name })),
+            }
+            : { code: "decoding", message, cause };
+        this.upscaling.reason = reason;
+        this.upscaling.hwdecCurrent = current;
+        return reason;
+    }
+    /**
+     * Send `video.upscaling.changed` with the state {@link TestHost.upscaling}
+     * describes now (without `enabled`), as the player does when it changes
+     * (player 0.5.25); a plugin listening with
+     * `plugin.video.upscaling.onChange` receives it. Nothing reaches a plugin
+     * that does not listen.
+     *
+     * @capability None.
+     *
+     * @example Show the new factor in the plugin's window
+     * The window resized: the test changes the area and the factor, sends
+     * the change, and checks that the plugin's window shows the new factor.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscaling.area = { width: 2560, height: 1440 };
+     * host.upscaling.factor = 1.33; // 1080p in a 1440p area
+     * host.upscalingChanged(); // as the player after the resize settled
+     * await host.settle();
+     * assert.equal(host.window("upscale").props.factor, "×1.33");
+     * ```
+     *
+     * @since 1.5.43
+     */
+    upscalingChanged() {
+        if (!this.subscriptions.has("video.upscaling.changed"))
+            return;
+        const { enabled: _, ...state } = this.#upscalingState(false);
+        this.emit("video.upscaling.changed", state);
+    }
     /** What `player.chapters()` lists while media is ready. */
     chapters = [];
     #overrides = new Map();
@@ -3481,12 +3578,20 @@ export class TestHost {
                 message: "the player has not checked the GPU yet; state() or set(true) checks it",
             };
         const requested = enabled && reason === null && factor !== null && factor > 1;
+        const { video, area, gpu, hwdecCurrent } = this.upscaling;
         return {
             available: reason === null,
-            reason: reason ? { ...reason } : null,
+            reason: reason
+                ? structuredClone(reason)
+                : null,
             enabled,
             requested,
             factor: requested ? factor : null,
+            video: video ? { ...video } : null,
+            area: area ? { ...area } : null,
+            gpu,
+            hwdecCurrent,
+            inChain: requested,
         };
     }
     /** `rendering.state` from {@link TestHost.rendering} and `videoRender.gpu`. */