@vestra-player/sdk 1.5.43 → 1.5.45

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.43: full reference
+# @vestra-player/sdk 1.5.45: 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.
 
@@ -1903,6 +1903,8 @@ host.handle("processing.replace", () => {
 
 `await host.settle()` after every action that makes the plugin talk to the player; `host.settle(400)` also lets debounces and timers due by then fire. Then assert on what the host recorded: `host.window(id).props` (kebab-case names), `host.command(id).state`, `host.osd`, `host.source`.
 
+`settle` does not wait for the once-a-second full update pass (SDK 1.5.45): after `host.setSource(...)` only the bindings that read a changed field of `plugin.player.state` run again. A value your plugin changed outside a handler (a timer, a promise continuation, a child process) without `plugin.update()` shows in the next full pass, at most about a second later; call `plugin.update()` in the plugin after such a change, or wait `await host.settle(1000)` in the test.
+
 `settle` waits only for calls to the player. Work the plugin does on its own (reading or parsing a file, a child process, a network request) can finish later on a loaded machine; poll the value you assert on instead:
 
 ```ts nocheck
@@ -3242,17 +3244,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.
 
@@ -3268,6 +3274,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
@@ -3283,7 +3376,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 |
 | --- | --- | --- | --- |
@@ -3775,14 +3868,18 @@ There is no cleanup function to return from `activate`. Because every resource i
 A plugin's state is plain variables. The SDK keeps the player in step with it through **bindings** and the **update pass**:
 
 - A binding is a function the SDK calls to get a current value: view.bind(() => props) for a window, panel or settings page, and the function form of a command's `enabled`, `checked`, `busy` and `reason` (Bindable).
-- In an update pass the SDK calls every binding of the plugin, compares each result with the value it last sent, and sends only what changed.
+- In an update pass the SDK calls the bindings of the plugin, compares each result with the value it last sent, and sends only what changed.
 
-Update passes run:
+A **full pass** calls every binding. It runs:
 
 - after every handler the SDK calls returns (a command's `run`, a view callback, an `onChange`, `onStatus`, `onEnd` or `onStop` listener), and again when the promise it returned settles;
-- after the player, subtitle, panel position, filter or export state changes;
+- after the subtitle, window, panel position, timeline, appearance, filter or export state changes;
 - when the plugin calls plugin.update().
 
+A **precise pass** follows a change of the player state (SDK 1.5.45). While media plays the player sends its state about ten times a second, mostly with only `position` changed. The SDK notes which fields of `plugin.player.state` each binding read the last time it ran (each `view.bind` function on its own; a command's four functions together) and calls only the bindings that read a field that changed. A panel whose list reads nothing of the player state is not rebuilt on every position tick; a label that shows the position is. `player.isCurrent` and `Media.current` count as reading the source. A `player.onChange` listener is followed by a full pass, as above, unless it returned synchronously and read only fields that did not change.
+
+A precise pass cannot see state the plugin changed by itself. So while precise passes leave bindings out, a full pass follows at least once a second: a variable your own timer changed without `plugin.update()` appears within about a second (before SDK 1.5.45 it usually appeared at the next position tick). Call `plugin.update()` after such a change to show it at once.
+
 Several requests within one microtask are merged into one pass, and every target has at most one write in flight: values that change meanwhile are merged into the next write. A binding that changes 60 times a second therefore costs one write per round trip, never a growing queue.
 
 One click, end to end (a bookmark window; the video is at 42 s):
@@ -3802,7 +3899,7 @@ sequenceDiagram
     S->>U: the label changes, Jump to bookmark is enabled
 ```
 
-The rule that follows: **state you change outside a handler, or after an `await` inside one, appears only at the next pass.** Changing a variable from your own `setInterval`, a socket callback or the middle of a long task shows nothing until something triggers a pass; call `plugin.update()` after such a change. Keep a slider responsive while dragging shows the pattern; How Slint and TypeScript talk explains `set` versus `bind` for views.
+The rule that follows: **state you change outside a handler, or after an `await` inside one, appears only at the next full pass.** Changing a variable from your own `setInterval`, a socket callback or the middle of a long task shows nothing until something triggers one (at most about a second while media plays); call `plugin.update()` after such a change. Keep a slider responsive while dragging shows the pattern; How Slint and TypeScript talk explains `set` versus `bind` for views.
 
 #### Stopping
 
@@ -3918,7 +4015,7 @@ const toggle = plugin.commands.add({
 
 - **The id is the command's identity.** It is unique within the plugin; the player knows the command as `<manifest id>/<id>`. The user's own key bindings are stored under that pair, so changing a title or moving the command to another menu keeps them.
 - **`path` puts it in the main menu.** Leave it out for a command that only has bindings or lives in a panel's context menu (Panel.showMenu); it then needs a `title`.
-- **State is declared, not pushed.** `enabled`, `checked`, `busy` and `reason` are values or functions (Bindable); `enabled` and `checked` may also be conditions from `plugin.when` (below). Functions are evaluated in every update pass and sent only when they change, so the menu's check mark follows the player without a listener you write. Command.set replaces them later.
+- **State is declared, not pushed.** `enabled`, `checked`, `busy` and `reason` are values or functions (Bindable); `enabled` and `checked` may also be conditions from `plugin.when` (below). Functions are evaluated in every full update pass, and after a player state change only if they read a field that changed; they are sent only when they change, so the menu's check mark follows the player without a listener you write. Command.set replaces them later.
 - **The player calls `run` only when it can run.** While a command is disabled or busy, neither its menu item nor its binding calls `run`; `reason` tells the user why (it appears in the menu and, for a key press, on the video).
 - **Titles and paths are fixed.** They cannot change in place. A menu that follows changing content (tracks, presets, a radio group) lives in a child scope that is disposed and rebuilt when the content changes; `order` keeps its place (Handles and scopes).
 - Disposing the command removes it from the menu and the binding table; the same id can be added again at once. The number of commands per plugin and per player is limited (Reference: limits); the limit stops runaway menus, so cap menus built from media content (tracks, chapters) yourself.
@@ -4175,7 +4272,7 @@ player.openStream (capability `producer.av`) makes a source whose picture and so
 
 #### Next and previous
 
-The player's **Previous** and **Next** (menu, keys, the bottom bar) are not tied to a playlist. One plugin at a time can **provide the sequence** with provideSequence, giving `next()`, `previous()` and two flags, `canNext` and `canPrevious`, which are bindings re-evaluated in every update pass.
+The player's **Previous** and **Next** (menu, keys, the bottom bar) are not tied to a playlist. One plugin at a time can **provide the sequence** with provideSequence, giving `next()`, `previous()` and two flags, `canNext` and `canPrevious`, which are bindings re-evaluated in every full update pass, and after a player state change only if they read a changed field.
 
 - Every plugin sees the flags as `player.state.can.next` and `can.previous`, and player.next() asks the provider to move; the provider's `next` runs in its own scope.
 - A second provider fails with `conflict` and does not fail activation; it is tried again when its flags change, so it takes over once the first provider goes away.
@@ -4536,15 +4633,22 @@ export component ListPanel inherits Rectangle {
 
 |                  | `set({ x })`                                                                            | `bind(() => ({ x }))`                                                                 |
 | ---------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| When it is sent  | Immediately (in the next write).                                                        | In every update pass, if `x` differs from the last value sent.                        |
+| When it is sent  | Immediately (in the next write).                                                        | In every full update pass, and after a player state change if the function read a changed field; when `x` differs from the last value sent. |
 | Same value again | Sent again. Use this to pull a control back to the model value after the user moved it. | Not sent. A field the user edited stays as the user left it until your value changes. |
 | Write fails      | Retried with back-off (0.25 s doubling up to 30 s).                                     | Not repeated until the value changes.                                                 |
 | Typical use      | One-off values: a document, a reset.                                                    | Everything derived from plugin state: labels, enabled flags, lists, status lines.     |
 
-Update passes run after every handler the SDK calls, after player and other state changes, and when you call plugin.update(); several requests are merged into one pass, and each view has at most one write in flight (The update pass has the details).
+Update passes run after every handler the SDK calls, after player and other state changes, and when you call plugin.update(); several requests are merged into one pass, and each view has at most one write in flight. After a player state change only the bind functions that read a changed field of `plugin.player.state` run again (The update pass has the details).
 
 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**:
@@ -5712,6 +5816,8 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [1.5.45](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1545) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. | — |
+| [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. | — |
@@ -6268,8 +6374,10 @@ interface CommandState {
 
 ### Bindable
 
-A value, or a function the SDK re-evaluates on every update pass (see
-Scope.update); only changes are sent to the player.
+A value, or a function the SDK re-evaluates on every full update pass,
+and after a player state change only if it read a field of
+`plugin.player.state` that changed (see Scope.update); only
+changes are sent to the player.
 
 ```ts
 type Bindable<T> = T | (() => T);
@@ -6278,9 +6386,9 @@ type Bindable<T> = T | (() => T);
 Example: Mix a computed state with a fixed one
 
 The Loop item carries a check mark while a loop is set and is always
-enabled. A function is evaluated again in every update pass (after each
-handler and player state change) and only changes are sent; a plain
-value never changes.
+enabled. A function is evaluated again in every full update pass (after
+each handler), and after a player state change only if it read a changed
+field; only changes are sent, and a plain value never changes.
 ```ts
 plugin.commands.add({
   id: "loop",
@@ -6701,8 +6809,9 @@ from the menu and the binding table; the id can be added again right away.
 
 The handle of one menu item and its keys. Its state (`enabled`, `checked`,
 `busy`, `reason`) is bound: functions given to Commands.add or
-Command.set are evaluated again in every update pass and only
-changes reach the player. Its title, path, bindings and button cannot
+Command.set are evaluated again in every full update pass (after
+a player state change only if they read a changed field of
+`plugin.player.state`) and only changes reach the player. Its title, path, bindings and button cannot
 change in place; dispose the command (or a child Scope) and add it
 again. Disposing it, its scope or stopping the plugin removes the menu
 item, its keys and its bar button.
@@ -6765,7 +6874,7 @@ const exportCommand = plugin.commands.add({
   path: ["@video", "Export…"],
   run: runExport,
 });
-// A function: re-evaluated in every update pass.
+// A function: re-evaluated in every full pass and when `phase` changes.
 exportCommand.set({ enabled: () => plugin.player.state.phase === "ready" });
 ```
 
@@ -7316,8 +7425,9 @@ a property back: a value the user changes reaches it only through a
 callback.
 
 `bind` is the usual way: the SDK re-evaluates bound functions in every
-update pass (after each handler it calls, after player state changes, on
-Scope.update) and sends only what changed, at most one write in
+full update pass (after each handler it calls, on Scope.update),
+and after a player state change those that read a changed field of
+`plugin.player.state`, and sends only what changed, at most one write in
 flight per view. `set` sends now, even an unchanged value.
 
 Writes that fail (a name the Slint file does not declare, a value of the
@@ -7420,7 +7530,11 @@ interface View {
    * Keep properties equal to a function of the plugin's state.
    *
    * The SDK calls `props` in every update pass (and right after `bind`) and
-   * sends the values that differ from the ones it sent last. Because an
+   * sends the values that differ from the ones it sent last. After a change
+   * of the player state alone it calls `props` only if it read a field of
+   * `plugin.player.state` that changed (SDK 1.5.45); a full pass follows
+   * after each handler, on Scope.update and at least once a second
+   * while the player state keeps changing. Because an
    * unchanged value is not sent again, text the user typed into an `in-out`
    * property stays until the plugin's value for it changes.
    *
@@ -7438,8 +7552,9 @@ interface View {
    * @example Show what is playing and whether it can seek
    * The status window always shows the current file and enables its seek
    * controls only for seekable sources. The SDK calls the function right
-   * away and again in every update pass (after player state changes and
-   * after each handler) and sends only the values that changed.
+   * away, again in every full update pass (after each handler) and after
+   * each change of `source` or `can`, and sends only the values that
+   * changed.
    * ```ts
    * const status = plugin.windows.create("ui/status.slint");
    * status.bind(() => ({
@@ -10848,8 +10963,8 @@ interface Player {
    * @example Drive the player's Next and Previous from a playlist
    * The player's Next and Previous items and keys play the plugin's list.
    * The player calls `next` and `previous` when the user asks; `canNext`
-   * and `canPrevious` are evaluated again after every handler the SDK runs,
-   * and while they return false the player disables its items ("No next
+   * and `canPrevious` are evaluated again after every handler the SDK runs
+   * (and after a player state change if they read a changed field), and while they return false the player disables its items ("No next
    * item").
    * ```ts
    * const playAt = async (at: number) => {
@@ -16902,6 +17017,13 @@ class TestHost implements Transport {
    * or parsing a file, a child process, a network request) is not waited
    * for: on a loaded machine it can finish after `settle()` returns. Poll
    * the result you assert on instead (second example).
+   *
+   * `settle()` does not wait for the SDK's once-a-second full update pass
+   * (SDK 1.5.45). After `setSource` (or another player state change) only
+   * the bindings that read a changed field of `plugin.player.state` run
+   * again; state the plugin changed outside a handler without
+   * `plugin.update()` shows only in the next full pass. Have the plugin
+   * call `plugin.update()` after such a change, or wait `settle(1000)`.
    * @param ms - Extra time to wait, for debounces and timers (default 0).
    * @capability None.
    * @throws Never.

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.43: 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.45: 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–2289.
+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: L2218–2291.
 
 **main.ts**
 
@@ -78,9 +78,9 @@ export default async function activate(plugin: Plugin) {
 - `secrets`: Secrets.get/set/delete
 - `rendering.manage`: Rendering.setPreference/restartPlayer
 - `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.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2292–2352.
 
-**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: L15364.
+**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–2021; TestHost: L15479.
 
 **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 L5846.
+- Others: PluginError, llms-full.txt L5952.
 
 ## 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–2289; Capabilities L2290–2350; Limits L2351–2496; Commands, menus and bindings L2497–3022; Platforms L3023–3053; Theme L3054–3312; Command line L3313–3370; Error codes L3371–3418; Translations L3419–3511; Test host L3512–3698
-- Explanation: How a plugin runs L3699–3897; Commands, menus and key bindings L3898–4052; Playback state, controls and sources L4053–4212; Video and audio processing L4213–4333; Windows, panels, settings pages, dialogs and the OSD L4334–4589; GPU and software rendering L4590–4606; The player's Rust core L4607–4948; How the player runs and talks to plugins L4949–5288
-- Guidelines: Plugin rules L5289–5300; Interface guidelines L5301–5417; Menu guidelines L5418–5476
-- Upgrading: Migrate a plugin to English source text L5477–5626; Migrating off package rollback (1.5.16, removed in 1.5.17) L5627–5704; Who must change, release by release L5705–5768
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5769–15037
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15038–17905
+- 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–2021; Publish a plugin L2022–2123; Troubleshooting L2124–2217
+- Reference: Manifest L2218–2291; Capabilities L2292–2352; Limits L2353–2498; Commands, menus and bindings L2499–3024; Platforms L3025–3055; Theme L3056–3405; Command line L3406–3463; Error codes L3464–3511; Translations L3512–3604; Test host L3605–3791
+- Explanation: How a plugin runs L3792–3994; Commands, menus and key bindings L3995–4149; Playback state, controls and sources L4150–4309; Video and audio processing L4310–4430; Windows, panels, settings pages, dialogs and the OSD L4431–4693; GPU and software rendering L4694–4710; The player's Rust core L4711–5052; How the player runs and talks to plugins L5053–5392
+- Guidelines: Plugin rules L5393–5404; Interface guidelines L5405–5521; Menu guidelines L5522–5580
+- Upgrading: Migrate a plugin to English source text L5581–5730; Migrating off package rollback (1.5.16, removed in 1.5.17) L5731–5808; Who must change, release by release L5809–5874
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5875–15152
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15153–18027
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L6185, Scope L5921, PluginError L5846, Disposable L5784
-- Commands L6772; When L6370; Windows L7709; Panels L9155; Dialogs L9825; Player L10566; video: VideoFilter L11446, VideoView L11546, RenderOptions L11633, VideoShaders L11711, VideoUpscaling L12069; audio: AudioFilter L11491; Subtitles L12305; media: MediaCapture L12709; Resolvers L12939; Packages L13341; Osd L11311; Host L11153; Clipboard L13670; Power L13757; Tools L13816; Storage L13968; System L14167; Secrets L14247; window: MainWindow L9472; App L9652; Rendering L14510; Bindings L13569; Ui L7061; Timeline L9384; Drops L8402; Appearance L8483; I18n L8716; Settings L8999.
+- Plugin L6291, Scope L6027, PluginError L5952, Disposable L5890
+- Commands L6881; When L6478; Windows L7824; Panels L9270; Dialogs L9940; Player L10681; video: VideoFilter L11561, VideoView L11661, RenderOptions L11748, VideoShaders L11826, VideoUpscaling L12184; audio: AudioFilter L11606; Subtitles L12420; media: MediaCapture L12824; Resolvers L13054; Packages L13456; Osd L11426; Host L11268; Clipboard L13785; Power L13872; Tools L13931; Storage L14083; System L14282; Secrets L14362; window: MainWindow L9587; App L9767; Rendering L14625; Bindings L13684; Ui L7170; Timeline L9499; Drops L8517; Appearance L8598; I18n L8831; Settings L9114.
 
 ## 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. L18340–18435
-- blur: A tool window with one slider that blurs the playing video. L18436–18703
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18704–19042
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19043–19235
-- panel-menu: A sidebar panel with its own right-click menu. L19236–19450
-- menus: Radio menu items, separator groups and a menu item whose title changes. L19451–19616
-- theme-widgets: A tool window drawn with the player's theme and widgets. L19617–19786
-- markdown: A window that shows a Markdown document. L19787–19989
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L19990–20163
+- hello: The README Quick start: one menu command and an on-screen message. L18462–18557
+- blur: A tool window with one slider that blurs the playing video. L18558–18825
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18826–19164
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19165–19357
+- panel-menu: A sidebar panel with its own right-click menu. L19358–19572
+- menus: Radio menu items, separator groups and a menu item whose title changes. L19573–19738
+- theme-widgets: A tool window drawn with the player's theme and widgets. L19739–19908
+- markdown: A window that shows a Markdown document. L19909–20111
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L20112–20285
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.43",
+  "version": "1.5.45",
   "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); }