@vestra-player/sdk 1.5.44 → 1.5.46

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.44: full reference
+# @vestra-player/sdk 1.5.46: 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
@@ -2282,6 +2284,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 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 |
+| 0.6.0 | PropValue |
 
 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).
 
@@ -2350,7 +2353,7 @@ The check follows types, not names: `plugin.player.seek`, `const { player } = pl
 
 ## Reference: Limits
 
-The player bounds what one request may cost it. The limits are guards against runaway plugins, not sizes to aim for: a plugin that needs to come close to one usually needs a different design (send the rows near the view, not the whole list). The SDK checks the same limits before it sends a request, so a plugin's own tests hit them too (TestHost enforces them). A name in code style is a constant you can import from `@vestra-player/sdk/testing`.
+The player bounds what one request may cost it. The limits are guards against runaway plugins, not sizes to aim for. Since player 0.6.0 a whole list fits (50,000 playlist rows): bind it and draw it with a Slint `ListView` (a long list should use one: a `for` builds every row). The SDK sends row patches, and an array property larger than one request in parts (SDK 1.5.46); only a property's top-level array without Markdown documents is split, so any other value, and each row, must fit in one request (a row of more than 512 KiB is refused with `limit`). The SDK checks the same limits before it sends a request, so a plugin's own tests hit them too (TestHost enforces them). A name in code style is a constant you can import from `@vestra-player/sdk/testing`.
 
 #### Commands
 
@@ -2378,10 +2381,10 @@ One value written to a window, panel or settings page property (View.set, View.b
 | Limit | Value | Meaning |
 | --- | --- | --- |
 | `UI_VALUE_LIMITS.depth` | 8 | Nesting depth; the value itself is depth 0. |
-| `UI_VALUE_LIMITS.values` | 16384 | Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one. |
-| `UI_VALUE_LIMITS.arrayRows` | 4096 | Rows of one array. |
+| `UI_VALUE_LIMITS.values` | 1048576 | Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one. |
+| `UI_VALUE_LIMITS.arrayRows` | 100000 | Rows of one array. |
 | `UI_VALUE_LIMITS.stringBytes` | 65536 (64 KiB) | UTF-8 bytes of one string or object field name. |
-| `UI_VALUE_LIMITS.textBytes` | 1048576 (1 MiB) | UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included. |
+| `UI_VALUE_LIMITS.textBytes` | 33554432 (32 MiB) | UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included. |
 
 #### Text values
 
@@ -3866,14 +3869,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):
@@ -3893,7 +3900,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
 
@@ -4009,7 +4016,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.
@@ -4266,7 +4273,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.
@@ -4627,12 +4634,12 @@ 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).
 
@@ -5810,6 +5817,8 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [1.5.46](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1546) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. | — |
+| [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. | — |
@@ -6367,8 +6376,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);
@@ -6377,9 +6388,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",
@@ -6800,8 +6811,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.
@@ -6864,7 +6876,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" });
 ```
 
@@ -7092,20 +7104,23 @@ ImageOptions.maxSide for small pictures such as logos and
 thumbnails.
 
 Limits per value (`UI_VALUE_LIMITS` in `@vestra-player/sdk/testing`,
-player 0.4.3; older players: 4096 values and 1024 rows): nesting depth 8,
-16384 values in total (every array, object, string, number, boolean and
-null counts, the value itself included; a document or an image is one), 4096 rows
-per array, 64 KiB per string or field name and 1 MiB of text in total,
-field names and the text of its Markdown documents included (256 KB per
-document). A list of rows with 8 fields is 9 values per row, so about
-1800 rows fit. The whole request must also fit the player's 1 MiB
-message. A value over a limit is refused with code `limit` and the
-property keeps what it showed (see View.set); `TestHost` refuses
-it the same way.
-
-The limits bound the work of one write, not the size of your data: for
-a list that can grow without bound, send the rows near the view and the
-row count, and move that window as the user scrolls.
+player 0.6.0; players 0.4.3 to 0.5: 16384 values, 4096 rows, 1 MiB of
+text): nesting depth 8, 1,048,576 values in total (every array, object,
+string, number, boolean and null counts, the value itself included; a
+document or an image is one), 100,000 rows per array, 64 KiB per string
+or field name and 32 MiB of text in total, field names and the text of
+its Markdown documents included (256 KB per document). A list of rows
+with 13 fields is 14 values per row, so 50,000 such rows fit. An array
+property larger than one 1 MiB request is sent in parts (SDK 1.5.46, a
+player that takes row patches); only the top-level array is split, so
+any other value, and each row, must fit in one request (a row of more
+than 512 KiB is refused with `limit`). A value over a limit is refused
+with code
+`limit` and the property keeps what it showed (see View.set);
+`TestHost` refuses it the same way.
+
+Bind a whole list and draw it with a Slint `ListView`, which builds only
+the rows on screen; the SDK sends what changed (row patches).
 
 ```ts
 type PropValue = PropData | ImageRef;
@@ -7415,8 +7430,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
@@ -7519,7 +7535,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.
    *
@@ -7537,8 +7557,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(() => ({
@@ -10947,8 +10968,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) => {
@@ -17001,6 +17022,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.
@@ -17831,53 +17859,41 @@ keeps what it showed) and reported to `Scope.onError`: a write by
 makes `Window.show` reject; a panel or settings page opens without it and
 the failure goes to the plugin's `onError`.
 
-They bound the work one write costs the player's interface thread; they
-are not meant as list sizes to aim for. A list that can grow without
-bound (a playlist, a history) should send the rows near the view and say
-how many there are, not the whole list.
+Since player 0.6.0 (SDK 1.5.46) they allow a whole list: a plugin binds
+all of its rows (a playlist of 50,000 entries fits) and the view draws
+them with a Slint `ListView`, which builds only the rows on screen. The
+SDK sends a changed array as row patches, and an array larger than one
+request (about 512 KiB of rows) as its first rows followed by `insert`
+patches of the rest; the player converts large writes off its interface
+thread. Before player 0.6.0 the limits were 4,096 rows, 16,384 values and
+1 MiB of text, so a long list had to be sent as a window of rows.
+
+In a row, `null` where the view declares an `image` shows no picture
+(player 0.6.0): rows without a thumbnail need no placeholder image.
 
 ```ts
 const UI_VALUE_LIMITS: {
   /** Nesting depth; the value itself is depth 0 (8). */
   readonly depth: 8;
-  /** Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one (16384). */
-  readonly values: 16384;
-  /** Rows of one array (4096). */
-  readonly arrayRows: 4096;
+  /**
+   * Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one (1,048,576; 16,384 before player 0.6.0).
+   */
+  readonly values: number;
+  /** Rows of one array (100,000; 4,096 before player 0.6.0). */
+  readonly arrayRows: 100000;
   /** UTF-8 bytes of one string or object field name (64 KiB). */
   readonly stringBytes: number;
-  /** UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included (1 MiB). */
+  /** UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included (32 MiB; 1 MiB before player 0.6.0). */
   readonly textBytes: number;
 };
 ```
 
-Example: Send a long playlist as a window of rows
+Example: Bind a whole list
 
-A list view shows any number of entries while each write stays small:
-the plugin sends only the rows around the scroll position plus the total,
-and the view reports where it scrolled to. After the `scrolled` handler
-returns, the SDK evaluates the `bind` function again and sends the new
-window. Each row object and each of its fields count as one value toward
-`values`, and so does the array holding them.
-```ts
-import { UI_VALUE_LIMITS } from "@vestra-player/sdk/testing";
+The view draws every row with a `ListView`; the SDK sends what changed.
 
-// 200 rows, or fewer if the limits were smaller: 2 fields per row make
-// 3 values (the row and its fields), plus 1 for the array.
-const size = Math.min(
-  200,
-  UI_VALUE_LIMITS.arrayRows,
-  Math.floor((UI_VALUE_LIMITS.values - 1) / 3),
-);
-let first = 0;
-list.bind(() => ({
-  total: entries.length,
-  rows: entries.slice(first, first + size),
-}));
-// The Slint view reports its first visible row; the window follows it.
-list.on("scrolled", (row: number) => {
-  first = Math.max(0, row - Math.floor(size / 2));
-});
+```ts
+list.bind(() => ({ rows: entries.map((e) => ({ ...e, selected: false })) }));
 ```
 
 ### IMAGE_LIMITS

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @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.
+> @vestra-player/sdk 1.5.46: 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–2292.
 
 **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: L2293–2353.
 
-**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.
+**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: L15484.
 
 **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 L5945.
+- Others: PluginError, llms-full.txt L5954.
 
 ## 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–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
+- 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–2292; Capabilities L2293–2353; Limits L2354–2499; Commands, menus and bindings L2500–3025; Platforms L3026–3056; Theme L3057–3406; Command line L3407–3464; Error codes L3465–3512; Translations L3513–3605; Test host L3606–3792
+- Explanation: How a plugin runs L3793–3995; Commands, menus and key bindings L3996–4150; Playback state, controls and sources L4151–4310; Video and audio processing L4311–4431; Windows, panels, settings pages, dialogs and the OSD L4432–4694; GPU and software rendering L4695–4711; The player's Rust core L4712–5053; How the player runs and talks to plugins L5054–5393
+- Guidelines: Plugin rules L5394–5405; Interface guidelines L5406–5522; Menu guidelines L5523–5581
+- Upgrading: Migrate a plugin to English source text L5582–5731; Migrating off package rollback (1.5.16, removed in 1.5.17) L5732–5809; Who must change, release by release L5810–5876
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5877–15157
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15158–18020
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- 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.
+- Plugin L6293, Scope L6029, PluginError L5954, Disposable L5892
+- Commands L6883; When L6480; Windows L7829; Panels L9275; Dialogs L9945; Player L10686; video: VideoFilter L11566, VideoView L11666, RenderOptions L11753, VideoShaders L11831, VideoUpscaling L12189; audio: AudioFilter L11611; Subtitles L12425; media: MediaCapture L12829; Resolvers L13059; Packages L13461; Osd L11431; Host L11273; Clipboard L13790; Power L13877; Tools L13936; Storage L14088; System L14287; Secrets L14367; window: MainWindow L9592; App L9772; Rendering L14630; Bindings L13689; Ui L7175; Timeline L9504; Drops L8522; Appearance L8603; I18n L8836; Settings L9119.
 
 ## 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. 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
+- hello: The README Quick start: one menu command and an on-screen message. L18455–18550
+- blur: A tool window with one slider that blurs the playing video. L18551–18818
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18819–19157
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19158–19350
+- panel-menu: A sidebar panel with its own right-click menu. L19351–19565
+- menus: Radio menu items, separator groups and a menu item whose title changes. L19566–19731
+- theme-widgets: A tool window drawn with the player's theme and widgets. L19732–19901
+- markdown: A window that shows a Markdown document. L19902–20104
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L20105–20278
 
 ## Optional
 

package/package.json

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