@vestra-player/sdk 1.5.42 → 1.5.44

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.42: full reference
+# @vestra-player/sdk 1.5.44: 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.
 
@@ -2281,6 +2281,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.16 | UpscalingReasonCode, UpscalingReason, UpscalingState, VideoUpscaling |
 | 0.5.20 | VideoShaders |
 | 0.5.21 | Scope.when, When, Bindings.onChange |
+| 0.5.25 | UpscalingReason.cause, UpscalingReason.plugins, UpscalingDecodingCause, UpscalingPlugin, UpscalingVideoSize, UpscalingState.video, UpscalingState.area, UpscalingState.gpu, UpscalingState.hwdecCurrent, UpscalingState.inChain, VideoUpscaling.onChange |
 
 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).
 
@@ -2318,7 +2319,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 |  |
+| `video.upscaling` | VideoUpscaling.state, VideoUpscaling.set, VideoUpscaling.onChange | — | 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:
 
@@ -3241,17 +3242,21 @@ Icon { name: "close"; width: 20px; height: 20px; }         // scaled
 | `checked` | in `bool` |  | Icon buttons: the "on" state, drawn in the accent colour. |
 | `clicked` | callback `()` |  |  |
 
-**`Slider`**: 2px line slider. Bar style (default): 8px round thumb, a white core in a 2px accent ring, gradient fill. Panel style (`panel: true`): 14×12 thumb, gradient fill. The track is `Theme.line` in both.
+**`Slider`**: 2px line slider. Bar style (default): 8px round thumb, a white core in a 2px accent ring, gradient fill. Panel style (`panel: true`): 14×12 thumb, gradient fill. The track is `Theme.line` in both. Keyboard (focused by Tab or `focus()`; a click does not take the focus, so the bar's volume slider leaves the arrows to seeking), as std-widgets' Slider: Left/Down and Right/Up move by `step`, Page Down/Up by 10 steps, Home/End to the ends; `changed` follows every move and `released` the key's release. Screen readers can increment, decrement or set the value.
 
 | Member | Kind | Default | Note |
 | --- | --- | --- | --- |
 | `value` | in-out `float` |  |  |
 | `minimum` | in `float` | `0` |  |
 | `maximum` | in `float` | `1` |  |
+| `step` | in `float` | `(root.maximum - root.minimum) / 20` | One key press: a twentieth of the range unless set. |
 | `enabled` | in `bool` | `true` |  |
 | `panel` | in `bool` |  |  |
+| `focusable` | in `bool` | `true` | false: Tab skips the slider (the bottom bar's seek and volume sliders, so Tab never moves the arrows from seeking to the slider); `focus()` still works. |
+| `has-focus` | out `bool` | `keys.has-focus` |  |
 | `changed` | callback `(float)` |  |  |
 | `released` | callback `(float)` |  |  |
+| `set-value` | function `(v: float)` |  | Clamped to the range; `changed` only when the value moves. |
 
 **`UrlInputRow`**: Link input: a multi-line input and [Open] [Cancel]. Enter or the confirm button accepts (Shift+Enter starts a new line), Esc or Cancel cancels. No validation here: the plugin checks the address.
 
@@ -3267,6 +3272,93 @@ Icon { name: "close"; width: 20px; height: 20px; }         // scaled
 | `focus-input` | function `()` |  |  |
 | `select-all` | function `()` |  |  |
 
+**`Check`**: Check box with a label that wraps onto more lines when the row is narrower than the label (the box stays beside the first line). A click or Space flips `checked`, then `toggled` reports the new state, as std-widgets' CheckBox: bind it two-way (`checked <=> Bridge.on`), or set it again from the plugin's data in a `changed` handler, since the click replaces a one-way binding. Plugin-decided (`self-toggle: false`, like Radio): a click or Space does not flip the box; `toggled` reports the state asked for (`!checked`) and the plugin sets `checked` when it agrees, for example after a confirmation, so a one-way binding (`checked: Bridge.on`) stays. Both modes also call `clicked`. Default style: a 13px box, accent when checked. Panel style (`panel: true`, the picture and audio workbenches' switches): a 12px box on `bg-bar` with a 6px `playing` square.
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `text` | in `string` |  |  |
+| `checked` | in-out `bool` |  |  |
+| `enabled` | in `bool` | `true` |  |
+| `panel` | in `bool` |  |  |
+| `self-toggle` | in `bool` | `true` | false: the plugin owns `checked` (see above). |
+| `has-focus` | out `bool` | `keys.has-focus` |  |
+| `toggled` | callback `(bool)` |  | The state after the click (self-toggle) or the state asked for. |
+| `clicked` | callback `()` |  |  |
+| `toggle` | function `()` |  | What a click does; also Space and the screen reader's default action. |
+
+**`RadioMark`**: The 12px radio dot alone, for rows a plugin lays out itself, such as the palette list with its previews. `hover` lights the ring; `focused` draws the focus ring.
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `checked` | in `bool` |  |  |
+| `hover` | in `bool` |  |  |
+| `enabled` | in `bool` | `true` |  |
+| `focused` | in `bool` |  |  |
+
+**`Radio`**: One radio choice: the mark, 4px, an 11px label. The plugin owns the state: `checked` is what it shows, a click or Space asks with `clicked`. For a set of choices from one list use RadioGroup, which also takes the arrow keys. (`focusable` and `focused` are RadioGroup's: its radios are one Tab stop, the group's.)
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `text` | in `string` |  |  |
+| `checked` | in `bool` |  |  |
+| `enabled` | in `bool` | `true` |  |
+| `focusable` | in `bool` | `true` |  |
+| `focused` | in `bool` |  |  |
+| `has-focus` | out `bool` | `keys.has-focus` |  |
+| `clicked` | callback `()` |  |  |
+
+**`RadioGroup`**: Radio choices from a list of labels, in a row (12px apart) or a column (`vertical`). One Tab stop; a click, or the arrow keys while the group has the focus (they wrap around), pick one: `current-index` changes and `selected` reports it, as std-widgets' RadioGroup.
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `model` | in `[string]` |  |  |
+| `current-index` | in-out `int` | `-1` |  |
+| `vertical` | in `bool` |  |  |
+| `enabled` | in `bool` | `true` |  |
+| `spacing` | in `length` | `root.vertical ? 0px : 12px` |  |
+| `has-focus` | out `bool` | `keys.has-focus` |  |
+| `selected` | callback `(int)` |  |  |
+| `select` | function `(index: int)` |  |  |
+
+**`Tab`**: One page tab: at least 74px, 12px label, dimmed unless `selected`; the selected tab has a 28px gradient stroke under its label, the others a rounded plate on hover. `emphasis` draws an unselected label in the accent colour (something waits there). Tabs lays them out; use Tab alone only for a strip with other content.
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `text` | in `string` |  |  |
+| `selected` | in `bool` |  |  |
+| `emphasis` | in `bool` |  |  |
+| `focused` | in `bool` |  |  |
+| `clicked` | callback `()` |  |  |
+
+**`Tabs`**: A 31px tab strip on `bg-bar` (the picture, audio and properties windows): one Tab per label, left-aligned. A click, or Left/Right/Home/End while the strip has the focus, picks a tab: `current-index` changes and `selected` reports it. The pages are the plugin's (show the one for current-index). Its min-width is the tabs' width, for a window that must fit them.
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `model` | in `[string]` |  |  |
+| `current-index` | in-out `int` | `0` |  |
+| `emphasis` | in `[bool]` |  | Per tab (same order as `model`, may be shorter): Tab's `emphasis`, the accent label of a tab where something waits ("Updates (2)"). |
+| `has-focus` | out `bool` | `keys.has-focus` |  |
+| `selected` | callback `(int)` |  |  |
+| `select` | function `(index: int)` |  |  |
+
+**`Choice`**: Compact 21px drop-down: the current label (11px, elided) and a small V; a click opens the list below it (Slint keeps the popup inside the window, moving it up when there is no room below). The list is a ListView (rows are created only while visible, so long lists such as output devices or plugin ids stay cheap) of at most `max-visible-rows` 20px rows; it is at least `popup-min-width` wide. Slint moves the popup into the window but does not shorten it: in a window shorter than the list, set `window-height: root.height` (the window's height) and the list is cut to fit, scrolling to reach every row. A Choice in a mounted panel or settings page cannot see its window's height; keep `max-visible-rows` small there. Keyboard: closed and focused (Tab or `focus()`), Up/Down/Home/End change the choice, Space, Enter, F4 or Alt+Down open the list; open, the arrows, Page Up/Down and Home/End move the lit row, Enter or Space picks it, Escape or a click outside closes the list without a change. A pick sets `current-index` and `selected` reports it (only a change), as std-widgets' ComboBox; the pick replaces a one-way binding, so bind `current-index` two-way or set it again in a `changed` handler. The labels are what the list shows: give translated text (@tr in the .slint file, or text values `plugin.i18n.text` from the plugin).
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `model` | in `[string]` |  |  |
+| `current-index` | in-out `int` | `0` |  |
+| `enabled` | in `bool` | `true` |  |
+| `max-visible-rows` | in `int` | `10` |  |
+| `popup-min-width` | in `length` | `0px` |  |
+| `window-height` | in `length` | `0px` | The window's height, when known: the list is never taller. |
+| `has-focus` | out `bool` | `keys.has-focus` |  |
+| `open` | out `bool` | `popup.is-open` |  |
+| `current-text` | out `string` | `root.current-index >= 0 && root.current-index < root.model.length ? root.model[root.current-index] : ""` |  |
+| `selected` | callback `(int)` |  |  |
+| `select` | function `(index: int)` |  |  |
+| `show-list` | function `()` |  |  |
+| `close-list` | function `()` |  |  |
+
 A component's public functions are called from your own Slint code, through an element id: `row.focus-input()` puts the keyboard focus into `UrlInputRow`'s input (call it when the window opens, for example from `init`), `row.select-all()` selects its text.
 
 #### Markdown
@@ -3282,7 +3374,7 @@ A component's public functions are called from your own Slint code, through an e
 | `link-clicked` | callback `(string)` |  |  |
 | `copy-code` | callback `(string)` |  |  |
 
-**`MarkdownView`**: A scrolling Markdown document.
+**`MarkdownView`**: A scrolling Markdown document: a `ListView` of its blocks, so only the blocks in view exist (a long document no longer builds every block). It draws as `MarkdownBlocks` in a column with `inset` padding would: `inset` above the first block, below the last and at both sides, 8px between.
 
 | Member | Kind | Default | Note |
 | --- | --- | --- | --- |
@@ -3654,6 +3746,8 @@ It rejects when nothing is bound to the key or the command it would run is busy.
 | TestHost.app | What `plugin.app` reports. |
 | TestHost.rendering | The player's rendering choice behind `plugin.rendering` (player 0.5.13). |
 | TestHost.upscaling | 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. |
+| TestHost.upscalingDecoding() | 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`). |
+| TestHost.upscalingChanged() | Send `video.upscaling.changed` with the state `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. |
 | TestHost.chapters | What `player.chapters()` lists while media is ready. |
 | TestHost.dataDirectory | `plugin.dataDirectory`: a fresh empty temporary directory, removed with the host on `stop()`. |
 | TestHost.manifestId | The manifest id of the plugin under test (set by `startPlugin`; `"test.plugin"` by default). |
@@ -4324,8 +4418,9 @@ plugin.video.shaders(id) (player 0.5.20) returns a VideoShaders handle: a list o
 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.
+- **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. From player 0.5.25 the reason's `cause` says which decoding stands in the way (`copy-back`, `hwdec-off`, `software`, `other-hwdec`), and with `copy-back` its `plugins` say whose filters, so a window can ask the user to turn them off there.
 - **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.
+- **Watch it while it runs.** From player 0.5.25 the state also has the video's and the area's size, the rendering GPU, the decoder and `inChain`, and onChange sends it as it changes while some plugin has upscaling on. A listener keeps the plugin running, so listen only while a window shows it.
 
 ## Explanation: Windows, panels, settings pages, dialogs and the OSD
 
@@ -4541,6 +4636,13 @@ Update passes run after every handler the SDK calls, after player and other stat
 
 The rule to remember: **state you change after an `await` inside a handler appears only when the handler finishes**, unless something else triggers a pass. Call `plugin.update()` right after changing it (see Keep a slider responsive while dragging).
 
+##### Arrays: only the changed rows are sent
+
+From player 0.6.0 and SDK 1.5.44, a changed array (a list's rows) is sent as the rows that changed: rows set, inserted, removed or moved, matched by a `key`, `id`, `rowId` or `row-id` field when every row has a unique one, else by position. The player writes those rows into the list Slint already shows, so selecting one row of a long list costs one row, not the whole list. Nothing changes in your code, and the TestHost's `props` still hold the whole array. Two consequences:
+
+- **Your Slint code must not write into the rows of an array property** (`rows[i].selected = true` in a handler). A whole write used to overwrite such a change on the next update; a row patch touches only the rows whose value changed in your plugin, so the edited row keeps the Slint-side value until your value for that row changes. Send the event to the plugin with a callback and change the row there.
+- **`set()` with an unchanged array sends the whole array**, as `set()` always sends: use it to pull a list back to your rows. A bound array whose rows did not change sends nothing.
+
 ##### Two-way controls
 
 A control whose value both the user and the plugin change (a slider, a switch, a text field, a combo box) needs a **two-way binding to an `in-out` property**:
@@ -5708,6 +5810,8 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [1.5.44](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1544) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. | — |
+| [1.5.43](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1543) | **Nobody.** Additions only, `apiVersion` stays `vestra/1`, no new capability. | — |
 | [1.5.42](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1542) | **Nobody.** Documentation only: no API changes, `apiVersion` stays `vestra/1`, no player version needed. | — |
 | [1.5.41](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1541) | **Nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. | — |
 | [1.5.40](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1540) | **Nobody.** Additions only, `apiVersion` stays `vestra/1`. | — |
@@ -11839,7 +11943,7 @@ in the order the player checks them (the first that holds is reported):
 | `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. |
+| `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. UpscalingReason.cause says which, and UpscalingReason.plugins whose filters (newer players; see there). |
 | `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
@@ -11883,6 +11987,16 @@ interface UpscalingReason {
   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;
+  /**
+   * With code `decoding` only: why the video is not decoded on the GPU that renders it (UpscalingDecodingCause). Absent with every other code, and from players before 0.5.25.
+   * @player 0.5.25; older players send `decoding` without a cause.
+   */
+  readonly cause?: UpscalingDecodingCause;
+  /**
+   * With cause `copy-back` only: the plugins whose video filters need the frames in memory, which is why the player switched to copy-back decoding, in the order the plugins started (each plugin once). Name them to the user, who can turn the filters off there. Empty when the copy-back decoding is not one the player chose for a filter (the user's own `hwdec` setting). Absent with any other cause, and from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly plugins?: readonly UpscalingPlugin[];
 }
 ```
 
@@ -11897,6 +12011,78 @@ const { available, reason } = await plugin.video.upscaling.state();
 if (!available && reason) console.log(`${reason.code}: ${reason.message}`);
 ```
 
+### UpscalingDecodingCause
+
+Why the video is not decoded on the GPU that renders it: the
+UpscalingReason.cause of a `decoding` reason (player 0.5.25). A
+newer player may add causes: show UpscalingReason.message for the
+ones you do not handle.
+
+| Cause | Meaning |
+| --- | --- |
+| `copy-back` | Decoded on the GPU and copied back to memory, because a plugin's video filter needs the frames there (UpscalingReason.plugins names it), or because of the user's `hwdec` setting. |
+| `hwdec-off` | Hardware decoding is turned off (mpv's `hwdec` is `no`). |
+| `software` | This video is decoded in software: a cover picture, a format the GPU does not decode, or a hardware decoder that failed. It passes with the next video. |
+| `other-hwdec` | This video is decoded with another hardware decoder than the one the upscaler needs. |
+
+- @player 0.5.25
+
+```ts
+type UpscalingDecodingCause = "copy-back" | "hwdec-off" | "software" | "other-hwdec" | (string & {});
+```
+
+Example: Name the plugins whose filters block upscaling
+
+A plugin's upscaling window explains a `decoding` reason by its cause,
+and for `copy-back` names the plugins whose filters stand in the way, so
+the user can turn them off there (a plugin cannot run another plugin's
+commands).
+```ts
+const { reason } = await plugin.video.upscaling.state();
+if (reason?.code === "decoding" && reason.cause === "copy-back") {
+  const names = (reason.plugins ?? []).map((p) => p.name).join(", ");
+  // Ask the user to reset those filters; the manifest names are not translated.
+  console.log(names ? `Turn off the video filters of ${names}` : reason.message);
+} else if (reason) console.log(reason.message);
+```
+
+### UpscalingPlugin
+
+A plugin named in an UpscalingReason: its manifest id and its
+name for people, as its manifest gives it (not translated).
+
+- @player 0.5.25
+
+```ts
+interface UpscalingPlugin {
+  /** The plugin's manifest id, for example `vestra.video`. */
+  readonly id: string;
+  /** The manifest's `name` as is (its id without one), for people. */
+  readonly name: string;
+}
+```
+
+### UpscalingVideoSize
+
+The video's size as the upscaler gets it (UpscalingState.video):
+the decoder's frame size, width and height swapped for the file's
+quarter-turn rotation metadata.
+
+- @player 0.5.25
+
+```ts
+interface UpscalingVideoSize {
+  /** The frames' stored width in pixels. */
+  readonly width: number;
+  /** The frames' stored height in pixels. */
+  readonly height: number;
+  /** The width the video is meant to be shown at (non-square pixels). */
+  readonly displayWidth: number;
+  /** The height the video is meant to be shown at. */
+  readonly displayHeight: number;
+}
+```
+
 ### UpscalingState
 
 What VideoUpscaling.state and VideoUpscaling.set report:
@@ -11928,6 +12114,36 @@ interface UpscalingState {
    * 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;
+  /**
+   * The video's size as the upscaler gets it; `null` while no video decodes. With UpscalingState.area it explains the factor. Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly video?: UpscalingVideoSize | null;
+  /**
+   * The area the video is shown in, in pixels (the upscaler scales the video to fit it); `null` while the player shows no video area. Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly area?: {
+    /** Width in physical pixels. */
+    readonly width: number;
+    /** Height in physical pixels. */
+    readonly height: number;
+  } | null;
+  /**
+   * The name of the GPU that renders, for example `NVIDIA GeForce RTX 4070 Laptop GPU`; `null` in software rendering and where the player does not know it (macOS, Linux). Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly gpu?: string | null;
+  /**
+   * The hardware decoder in use for this video, as mpv names it (`d3d11va`, `d3d11va-copy`; `no` for software decoding); `null` while no video decodes. For people and logs: branch on UpscalingReason.cause. Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly hwdecCurrent?: string | null;
+  /**
+   * The upscaler is in the player's video filter chain now, read from the chain itself (`requested` is what the player asked for; they differ only for a moment, while the chain changes). Still not a sign that the GPU upscales: the driver gives none (see the remarks). Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly inChain?: boolean;
 }
 ```
 
@@ -12036,6 +12252,46 @@ interface VideoUpscaling {
    * ```
    */
   set(enabled: boolean): Promise<UpscalingState>;
+  /**
+   * Call `listener` with the new state whenever it changes while some plugin has upscaling on: the factor, whether the upscaler is in the chain, the reason, the video's and the area's size, the decoder. A window that shows how upscaling runs listens instead of polling VideoUpscaling.state.
+   *
+   * The player looks about five times a second while upscaling is on for
+   * any plugin (a window resize sends at most that many), and sends a
+   * change only when something differs; after the last plugin turns it
+   * off one more change says so, then nothing until it is on again: read
+   * VideoUpscaling.state when you need the state then. Nothing is
+   * sent before the player's GPU check ran (the first `state()` or
+   * `set(true)` of any plugin). `enabled` is this plugin's own request, as
+   * in `state()`. The message of a `rendering` reason can be shorter than
+   * the one `state()` gives (it may leave out what to do).
+   *
+   * **A listener keeps the plugin running.** `video.upscaling.changed` is
+   * not an event the player wakes a stopped plugin for: while the plugin
+   * listens, the player does not stop it while idle (lazy activation), even
+   * with upscaling off. Listen only while a window that shows the state is
+   * open, and dispose of the listener when it closes. Players before 0.5.25 do not know the event: the listener
+   * never fires and the SDK logs that the player refused the subscription.
+   * @capability video.upscaling
+   * @param listener - Receives the new state.
+   * @returns Stops listening; also when the scope that added it is disposed.
+   * @throws capability (synchronously) The manifest does not declare `video.upscaling`.
+   * @player 0.5.25
+   * @example Show how upscaling runs while a window is open
+   * The plugin's window shows the factor, the sizes and the GPU while it
+   * is open; the listener goes when the window closes, so the plugin can
+   * be stopped while idle again.
+   * ```ts
+   * // When the window opens:
+   * const watch = plugin.video.upscaling.onChange((state) => {
+   *   const video = state.video ? `${state.video.width}×${state.video.height}` : "no video";
+   *   const area = state.area ? `${state.area.width}×${state.area.height}` : "—";
+   *   console.log(`${video} → ${area}, ×${state.factor ?? 1}, ${state.gpu ?? "no GPU"}`);
+   * });
+   * // When it closes: stop listening (it keeps the plugin running).
+   * await watch.dispose();
+   * ```
+   */
+  onChange(listener: (state: UpscalingState) => void): Disposable;
 }
 ```
 
@@ -16227,7 +16483,50 @@ 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 TestHost.upscalingChanged to tell a listening plugin.
+   * @capability None.
+   * @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
+   * 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/);
+   * ```
+   */
+  upscalingDecoding(cause: UpscalingDecodingCause, plugins?: readonly UpscalingPlugin[]): UpscalingReason;
+  /**
+   * Send `video.upscaling.changed` with the state 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
+   * 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");
+   * ```
+   */
+  upscalingChanged(): void;
   /** 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.42: 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 (the player's built-in plugins share one). 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.44: 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 (the player's built-in plugins share one). 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: L2216–2288.
+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: L2216–2289.
 
 **main.ts**
 
@@ -77,10 +77,10 @@ export default async function activate(plugin: Plugin) {
 - `ui.theme`: Appearance.set/setLanguage
 - `secrets`: Secrets.get/set/delete
 - `rendering.manage`: Rendering.setPreference/restartPlayer
-- `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: L2289–2349.
+- `video.upscaling`: VideoUpscaling.state/set/onChange
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2290–2350.
 
-**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: L1861–2019; TestHost: L15207.
+**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: L1861–2019; TestHost: L15463.
 
 **Command line**
 
@@ -108,40 +108,40 @@ 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 L5841.
+- Others: PluginError, llms-full.txt L5945.
 
 ## 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–134; Add a window L135–213; Add settings and translations L214–367; Test, check, pack and publish L368–424; Write your own blur kernel L425–685
 - How-to: Control playback L686–854; Store a plugin's data L855–961; Load subtitles from a plugin L962–1074; Keep a slider responsive while dragging L1075–1262; Remember a window's state between runs L1263–1414; Offer a GPU rendering switch L1415–1540; Keep a command's state without keeping the plugin running L1541–1697; Translate a plugin L1698–1860; Test a plugin L1861–2019; Publish a plugin L2020–2121; Troubleshooting L2122–2215
-- Reference: Manifest L2216–2288; Capabilities L2289–2349; Limits L2350–2495; Commands, menus and bindings L2496–3021; Platforms L3022–3052; Theme L3053–3311; Command line L3312–3369; Error codes L3370–3417; Translations L3418–3510; Test host L3511–3695
-- Explanation: How a plugin runs L3696–3894; Commands, menus and key bindings L3895–4049; Playback state, controls and sources L4050–4209; Video and audio processing L4210–4329; Windows, panels, settings pages, dialogs and the OSD L4330–4585; GPU and software rendering L4586–4602; The player's Rust core L4603–4944; How the player runs and talks to plugins L4945–5284
-- Guidelines: Plugin rules L5285–5296; Interface guidelines L5297–5413; Menu guidelines L5414–5472
-- Upgrading: Migrate a plugin to English source text L5473–5622; Migrating off package rollback (1.5.16, removed in 1.5.17) L5623–5700; Who must change, release by release L5701–5763
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5764–14880
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L14881–17705
+- Reference: Manifest L2216–2289; Capabilities L2290–2350; Limits L2351–2496; Commands, menus and bindings L2497–3022; Platforms L3023–3053; Theme L3054–3403; Command line L3404–3461; Error codes L3462–3509; Translations L3510–3602; Test host L3603–3789
+- Explanation: How a plugin runs L3790–3988; Commands, menus and key bindings L3989–4143; Playback state, controls and sources L4144–4303; Video and audio processing L4304–4424; Windows, panels, settings pages, dialogs and the OSD L4425–4687; GPU and software rendering L4688–4704; The player's Rust core L4705–5046; How the player runs and talks to plugins L5047–5386
+- Guidelines: Plugin rules L5387–5398; Interface guidelines L5399–5515; Menu guidelines L5516–5574
+- Upgrading: Migrate a plugin to English source text L5575–5724; Migrating off package rollback (1.5.16, removed in 1.5.17) L5725–5802; Who must change, release by release L5803–5867
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5868–15136
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15137–18004
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L6180, Scope L5916, PluginError L5841, Disposable L5779
-- Commands L6767; When L6365; Windows L7704; Panels L9150; Dialogs L9820; Player L10561; video: VideoFilter L11441, VideoView L11541, RenderOptions L11628, VideoShaders L11706, VideoUpscaling L11952; audio: AudioFilter L11486; Subtitles L12148; media: MediaCapture L12552; Resolvers L12782; Packages L13184; Osd L11306; Host L11148; Clipboard L13513; Power L13600; Tools L13659; Storage L13811; System L14010; Secrets L14090; window: MainWindow L9467; App L9647; Rendering L14353; Bindings L13412; Ui L7056; Timeline L9379; Drops L8397; Appearance L8478; I18n L8711; Settings L8994.
+- Plugin L6284, Scope L6020, PluginError L5945, Disposable L5883
+- Commands L6871; When L6469; Windows L7808; Panels L9254; Dialogs L9924; Player L10665; video: VideoFilter L11545, VideoView L11645, RenderOptions L11732, VideoShaders L11810, VideoUpscaling L12168; audio: AudioFilter L11590; Subtitles L12404; media: MediaCapture L12808; Resolvers L13038; Packages L13440; Osd L11410; Host L11252; Clipboard L13769; Power L13856; Tools L13915; Storage L14067; System L14266; Secrets L14346; window: MainWindow L9571; App L9751; Rendering L14609; Bindings L13668; Ui L7160; Timeline L9483; Drops L8501; Appearance L8582; I18n L8815; Settings L9098.
 
 ## 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. L18140–18235
-- blur: A tool window with one slider that blurs the playing video. L18236–18503
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18504–18842
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L18843–19035
-- panel-menu: A sidebar panel with its own right-click menu. L19036–19250
-- menus: Radio menu items, separator groups and a menu item whose title changes. L19251–19416
-- theme-widgets: A tool window drawn with the player's theme and widgets. L19417–19586
-- markdown: A window that shows a Markdown document. L19587–19789
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L19790–19963
+- hello: The README Quick start: one menu command and an on-screen message. L18439–18534
+- blur: A tool window with one slider that blurs the playing video. L18535–18802
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18803–19141
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19142–19334
+- panel-menu: A sidebar panel with its own right-click menu. L19335–19549
+- menus: Radio menu items, separator groups and a menu item whose title changes. L19550–19715
+- theme-widgets: A tool window drawn with the player's theme and widgets. L19716–19885
+- markdown: A window that shows a Markdown document. L19886–20088
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L20089–20262
 
 ## Optional
 

package/package.json

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

package/slint/vestra/markdown.slint

@@ -9,7 +9,7 @@
 // row (a chat message: a `[MarkdownBlock]` field of the row's struct).
 // `code-copy: true` adds a Copy button to code blocks that reports
 // `copy-code(code)`; the plugin copies it (`plugin.clipboard`).
-import { ScrollView } from "std-widgets.slint";
+import { ListView } from "std-widgets.slint";
 import { Theme } from "theme.slint";
 import { Icon } from "icons.slint";
 
@@ -234,7 +234,10 @@ export component MarkdownBlocks inherits Rectangle {
     }
 }
 
-// A scrolling Markdown document.
+// A scrolling Markdown document: a `ListView` of its blocks, so only the
+// blocks in view exist (a long document no longer builds every block). It
+// draws as `MarkdownBlocks` in a column with `inset` padding would: `inset`
+// above the first block, below the last and at both sides, 8px between.
 export component MarkdownView inherits Rectangle {
     in property <[MarkdownBlock]> blocks;
     // Space around the document.
@@ -243,17 +246,20 @@ export component MarkdownView inherits Rectangle {
     in property <bool> code-copy: false;
     callback link-clicked(string);
     callback copy-code(string);
-    scroll := ScrollView {
+    list := ListView {
         width: 100%;
         height: 100%;
-        content-width: self.visible-width;
-        content-height: column.preferred-height;
-        column := VerticalLayout {
-            width: scroll.visible-width;
-            padding: root.inset;
-            alignment: start;
-            MarkdownBlocks {
-                blocks: root.blocks;
+        for block[i] in root.blocks: Rectangle {
+            property <length> top: i == 0 ? root.inset : 0px;
+            height: self.top + view.preferred-height
+                + (i == root.blocks.length - 1 ? root.inset : 8px);
+            view := MarkdownBlockView {
+                x: root.inset;
+                y: parent.top;
+                width: max(0px, parent.width - 2 * root.inset);
+                height: self.preferred-height;
+                block: block;
+                available: self.width;
                 code-copy: root.code-copy;
                 link-clicked(url) => { root.link-clicked(url); }
                 copy-code(code) => { root.copy-code(code); }