@vestra-player/sdk 1.5.18 → 1.5.21

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.18: full reference
+# @vestra-player/sdk 1.5.21: 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.
 
@@ -445,7 +445,7 @@ Key names describe keys, not characters, with two deliberate exceptions:
 - **Option combinations match the physical key**, so `Alt+O` fires for ⌥O although that key types `ø`, and dead keys (⌥E, ⌥N…) fire too. On layouts that need Option to type a symbol (German ⌥5 = ``, ⌥L = `@`), a binding for the typed symbol (`"["`, `"@"`) wins over one for the physical key (`Alt+5`).
 - **`Ctrl` is portable, `Cmd` is not.** On macOS `Ctrl+X` fires for both ⌃X and ⌘X, `Cmd+X` only for ⌘X. On Windows `Cmd` is the Windows logo key, which the system mostly keeps, so write `Ctrl+…` for a binding that works on both systems.
 
-Mouse bindings apply only over the video area. `Mouse:LeftDoubleClick:LeftHalf` and `:RightHalf` win over the plain double click; wheel bindings count accumulated scroll steps. The right button is reserved for the context menu, and a left drag in window mode moves the window instead of clicking. A `Mouse:LeftClick` fires on release, except when the same modifiers also have a double-click binding and the click's command is not checkable: then the player waits the system's double-click interval to tell a click from a double click. (A checkable command such as play/pause runs at once; a double click runs it twice, which restores its state, and the double-click binding still fires.)
+Mouse bindings apply only over the video area. `Mouse:LeftDoubleClick:LeftHalf` and `:RightHalf` win over the plain double click; wheel bindings count accumulated scroll steps. The right button is reserved for the context menu, and a left drag in window mode moves the window instead of clicking. A `Mouse:LeftClick` fires on release, except when the same modifiers also have a double-click binding and the click's command is not checkable: then the player waits the system's double-click interval to tell a click from a double click. (A checkable command such as play/pause runs at once; a double click runs it twice, which restores its state, and the double-click binding still fires.) The player's defaults (player 0.5.2): a left click on the video is Play/Pause and nothing is bound to a double click (up to 0.5.1 a double click was Toggle Fullscreen); a click whose command is disabled does nothing.
 
 ##### The user's bindings
 
@@ -579,10 +579,27 @@ The player's **Previous** and **Next** (menu, keys, the bottom bar) are not tied
 
 #### Core actions
 
-Play/pause, stop, previous/next, frame steps, relative seeks, speed, volume and mute are **core actions**: commands the player registers itself, so they work with no plugin running. plugin.host.run(action) runs one exactly as its menu item or key would, with the same checks and the same on-screen text. A plugin's play button should call `host.run("play-pause")` rather than `setPaused`, so that it behaves like the Space key in every case (restart after the end, the "Paused" message, disabled without a source).
+Play/pause, stop, previous/next, frame steps, relative seeks, speed, volume and mute are **core actions**: commands the player registers itself, so they work with no plugin running. plugin.host.run(action) runs one exactly as its menu item or key would, with the same checks and the same on-screen text. A plugin's play button should call `host.run("play-pause")` rather than `setPaused`, so that it behaves like the Space key in every case (restart after the end, the "Paused" message, disabled without a source). A fullscreen button calls `host.run("fullscreen")` (player 0.5.2), which toggles the main window like Enter; show the button's state from `window.state.fullscreen`.
 
 The difference from the `Player` methods: a `Player` control is a precise operation the plugin is responsible for (conditional, silent, its own error handling); a core action is the user's action, performed on the plugin's behalf. The action ids, menu places and default keys are in Reference: commands; how keys reach them is in Commands, menus and key bindings.
 
+##### Step seeks: exact or keyframe
+
+← / → (`seek-backward` / `seek-forward`) seek by the step that player.setStepSeek sets (5 s by default). By default they land on the exact time, which on a file with keyframes far apart means decoding from the previous keyframe first: a visible stall on 4K video. `setStepSeek({ seconds, keyframes: true })` (player 0.5.1, SDK 1.5.19) makes them land on a keyframe instead: forward on the first keyframe at or after position + step, backward on the last at or before position − step, and every press moves. Presses during a seek add up and continue from where it landed, and the on-screen text shows the landed time. Sources without moving video still seek exactly. The seek bar, `player.seek`, scrubs, chapters, loops and `player.step` are never affected.
+
+For more steps of your own (Ctrl+→ and the like), call `plugin.host.run("seek-forward", { seconds: 30 })`: the same checks, mode, accumulation and text as →. In keyframe mode it resolves once the seek has landed, so `player.state.position` is current afterwards; do not show your own text for it. Set `"minPlayerVersion": "0.5.1"` when you rely on either option: older players ignore them.
+
+```ts
+const keyframes = true; // the plugin's own setting
+await plugin.player.setStepSeek({ seconds: 5, keyframes });
+const seek = (delta: number) =>
+  plugin.host.run(delta < 0 ? "seek-backward" : "seek-forward", {
+    seconds: Math.abs(delta),
+  });
+```
+
+In tests, `TestHost.keyframes` models the source's keyframes, and `host.coreSeeks` records each step seek with where it landed.
+
 ## Concept: Video and audio processing
 
 A plugin can change what the user sees and hears in three different places. They look alike in the API (each is a handle with `set`, a `status` and `onStatus`), but they act at different stages and have different owners, so choosing the right one matters:
@@ -856,7 +873,8 @@ export component ListPanel inherits Rectangle {
 ##### Names and values
 
 - Write names in camelCase or kebab-case in TypeScript: the SDK turns every capital letter into `-` plus the lower-case letter (`canMark` → `can-mark`, `strengthChanged` → `strength-changed`). Fields inside struct values are **not** converted, so spell struct fields exactly as the Slint struct does (and without `_`, which Slint treats as `-`).
-- Values must be JSON: booleans, numbers, strings, arrays (Slint models) and objects (Slint structs). Two exceptions: an image from ui.image, only as the **whole** value of an `image` property (nested in an array or object it is `invalid`), and a document from ui.markdown wherever the Slint type is `[MarkdownBlock]`: the whole value, or (SDK 1.5.4, the player after 0.4.0) a field at any depth, such as the `body` of each message in a chat list.
+- Values must be JSON: booleans, numbers, strings, arrays (Slint models) and objects (Slint structs). Two exceptions: an image from ui.image or ui.remoteImage wherever the Slint type is `image`: the whole value, or (SDK 1.5.19, player 0.5.1) a field at any depth, such as the logo of each row of a list; and a document from ui.markdown wherever the Slint type is `[MarkdownBlock]`: the whole value, or (SDK 1.5.4, the player after 0.4.0) a field at any depth, such as the `body` of each message in a chat list.
+- Images in rows: give small pictures `maxSide` (about twice the drawn size, `64` for a 32 px logo), so that the player decodes them small. The images nested in one view's values may show at most 32 MB of decoded pixels together; a write past that is refused with `limit`. A nested image whose file fails the player's checks is drawn empty, and the rest of the row is shown. Rows with images update in place, so a `ListView` keeps its scroll position when the list is written again.
 - Every name must exist in the Slint file. Writing a property the file does not declare makes a tool window's `show()` or a panel's `ready` fail, and in a settings page it keeps the Options window from opening; for a tool window, so does a callback bound with `on()` that the file does not declare. Once the view is open, such writes are reported to onError.
 
 ##### set, bind and the update pass
@@ -2157,7 +2175,8 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.4.1 | PluginError, FileResolverOptions, PackageCandidate.install, PluginWarning.code, Packages.validate |
 | 0.4.2 | Resolvers.fileTypes, Resolvers.onFileTypesChange |
 | 0.4.3 | CommandOptions.path, PropValue, View.set, Appearance.setLanguage, TemplateArgs, Text, ConfirmOptions.args, OsdPanel.set, OsdPanelOptions.maxColumns, Osd.show |
-| 0.5.1 | SlotState.reason, Panel.setInteraction, PlaybackStats.presentedFps |
+| 0.5.1 | ImageRef, ImageOptions.maxSide, PropValue, Ui.image, Ui.remoteImage, SlotState.reason, Panel.setInteraction, PlaybackStats.presentedFps, Player.setStepSeek, Host.run, Packages.reload |
+| 0.5.2 | HostAction |
 
 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).
 
@@ -2178,7 +2197,7 @@ A plugin lists what it may do in the manifest's `capabilities` (Manifest). A cal
 | `ui.window` | Windows.create | — | Open tool windows |  |
 | `ui.mount` | Panels.mount, Panels.bottom, Panels.sidebar, Panels.backdrop, PanelSlot.onChange, Panel.onChange, BackdropSlot.onChange | — | Show panels in the bottom bar, the sidebar or behind the video |  |
 | `ui.dialog` | Dialogs.confirm, Dialogs.openFile, Dialogs.openFiles, Dialogs.openDirectory, Dialogs.saveFile | — | Show file pickers and confirmations |  |
-| `plugins.manage` | Packages.validate, Packages.validateArchive, Packages.setEnabled, Packages.uninstall | — | Install, uninstall and disable other plugins | yes |
+| `plugins.manage` | Packages.validate, Packages.validateArchive, Packages.setEnabled, Packages.reload, Packages.uninstall | — | Install, uninstall and disable other plugins | yes |
 | `processing.video` | Plugin.video.filter, Plugin.video.view, Plugin.video.render | `playback.read` | Process the picture (filters, shaders) |  |
 | `processing.audio` | Plugin.audio.filter | `playback.read`, `events` | Process the sound |  |
 | `subtitles.read` | Subtitles.state, Subtitles.onChange, Subtitles.refresh | — | Read subtitles |  |
@@ -2392,7 +2411,7 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Copy to Clipboard ▸ File Name |  | `vestra.playback/copy-name` |
 | Copy to Clipboard ▸ Folder Path |  | `vestra.playback/copy-folder` |
 | Copy to Clipboard ▸ Full Path |  | `vestra.playback/copy-path` |
-| Playback ▸ Play/Pause | `Space` | `host/play-pause` |
+| Playback ▸ Play/Pause | `Space`, `Mouse:LeftClick` | `host/play-pause` |
 | Playback ▸ Previous | `PageUp`, `Mouse:X1` | `host/previous` |
 | Playback ▸ Next | `PageDown`, `Mouse:X2` | `host/next` |
 | Playback ▸ Seek ▸ Previous Frame | `D` | `host/frame-back` |
@@ -2622,7 +2641,7 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Emulator ▸ Open NES ROM… |  | `vestra.nes/nes.open` |
 | Emulator ▸ Stop NES |  | `vestra.nes/nes.stop` |
 | Emulator ▸ NES Tools… |  | `vestra.nes/nes.window` |
-| Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11`, `Mouse:LeftDoubleClick` | `host/fullscreen` |
+| Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11` | `host/fullscreen` |
 | Screen ▸ Picture-in-Picture |  | `vestra.window/pip` |
 | Screen ▸ Mini Size | ``` | `vestra.window/mini` |
 | Screen ▸ 0.5× | `1` | `vestra.window/size.0.5` |
@@ -2651,7 +2670,6 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Settings ▸ Keyboard Shortcuts… |  | `vestra.hotkeys/keys` |
 | Settings ▸ Mouse… |  | `vestra.hotkeys/mouse` |
 | Settings ▸ Ignore Default Shortcuts |  | `vestra.hotkeys/ignore-defaults` |
-| Settings ▸ Plugin Manager… |  | `vestra.plugins/manage` |
 | Settings ▸ Appearance ▸ Vestra Dark |  | `vestra.preferences/theme.vestra` |
 | Settings ▸ Appearance ▸ Vestra Light |  | `vestra.preferences/theme.vestra-light` |
 | Settings ▸ Appearance ▸ Show Logo When Idle |  | `vestra.visualizer/idle-logo` |
@@ -2736,7 +2754,7 @@ The player's own playback commands, which plugin.host.run runs by id (capability
 | Action | Menu item | Default bindings |
 | --- | --- | --- |
 | `stop` | Close | `F4` |
-| `play-pause` | Playback ▸ Play/Pause | `Space` |
+| `play-pause` | Playback ▸ Play/Pause | `Space`, `Mouse:LeftClick` |
 | `previous` | Playback ▸ Previous | `PageUp`, `Mouse:X1` |
 | `next` | Playback ▸ Next | `PageDown`, `Mouse:X2` |
 | `frame-back` | Playback ▸ Seek ▸ Previous Frame | `D` |
@@ -2749,6 +2767,7 @@ The player's own playback commands, which plugin.host.run runs by id (capability
 | `volume-up` | Audio ▸ Volume + | `ArrowUp`, `Mouse:WheelUp` |
 | `volume-down` | Audio ▸ Volume − | `ArrowDown`, `Mouse:WheelDown` |
 | `mute` | Audio ▸ Mute | `M` |
+| `fullscreen` | Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11` |
 
 The player also owns **Toggle Fullscreen** (`host/fullscreen`), **Leave Fullscreen** (`host/exit-fullscreen`, `Escape`, only in fullscreen) and **Quit** (`host/quit`); their keys are in Built-in commands.
 
@@ -2923,17 +2942,19 @@ Icon { name: "close"; width: 20px; height: 20px; }         // scaled
 | `add` | 10 × 10 | 1.5px |
 | `remove` | 10 × 10 | 1.5px |
 | `sort` | 10 × 10 | 1.5px |
+| `fullscreen` | 14 × 12 | 1.5px |
+| `exit-fullscreen` | 14 × 12 | 1.5px |
 
 #### Widgets
 
 `@vestra/widgets.slint`: compact controls drawn with the theme. Other controls come from `std-widgets.slint`.
 
-**`ToolTipArea`**: Hover for 600 ms to show `text` beside the pointer. The tip closes when the pointer leaves or presses; it shows again on the next hover.
+**`ToolTipArea`**: Hover for about half a second to show `text` beside the pointer. The tip closes when the pointer leaves, or presses on content that does not take the press itself; it shows again on the next hover. It is Slint's input-transparent tooltip: every press reaches the control under the pointer, and the tip does not take the keyboard focus. (Up to SDK 1.5.20 the tip was a PopupWindow, which swallowed the first press after it showed and took the focus while it was open.)
 
 | Member | Kind | Default | Note |
 | --- | --- | --- | --- |
 | `text` | in `string` |  |  |
-| `showing` | out `bool` |  | The tip is showing (read-only). |
+| `showing` | out `bool` |  | The tip is showing (read-only); it follows the tip's delay closely, not exactly. |
 
 **`Button`**: Dialog button: text (21px, or 18px when `small`), or an icon button when `text` is empty and `icon` holds Path data drawn in an icon-width × icon-height viewbox (filled, or 1.5px round-capped lines when `stroked`, as the @vestra/icons.slint set). The caller sizes icon buttons.
 
@@ -3537,6 +3558,20 @@ interface ImageRef {
 }
 ```
 
+### ImageOptions
+
+Options of Ui.image and Ui.remoteImage.
+
+```ts
+interface ImageOptions {
+  /**
+   * Decode the image scaled down, aspect kept, so that neither side is over this many pixels (an integer 1–4096); smaller images stay as they are. Use about twice the drawn size (64 for a 32 px logo) so that it stays sharp on high-density screens. It keeps the decoded memory small: a 1024×1024 icon is 4 MB decoded, 16 KB at `maxSide: 64`.
+   * @player 0.5.1; older players refuse the reference (`invalid`).
+   */
+  maxSide?: number;
+}
+```
+
 ### MarkdownRef
 
 A Markdown document for `MarkdownView` or `MarkdownBlocks`, made by
@@ -3571,9 +3606,8 @@ interface MarkdownOptions {
 
 ### PropValue
 
-The value of one Slint property: JSON with Markdown documents at any
-depth (PropData), or an image as the whole value of an `image`
-property.
+The value of one Slint property: JSON with Markdown documents and images
+at any depth (PropData).
 
 ```ts
 type PropValue = PropData | ImageRef;
@@ -3581,11 +3615,11 @@ type PropValue = PropData | ImageRef;
 
 ### PropData
 
-JSON whose values may also be Markdown documents, at any depth: the part
-of PropValue that nests.
+JSON whose values may also be Markdown documents and (SDK 1.5.19) images,
+at any depth: the part of PropValue that nests.
 
 ```ts
-type PropData = null | boolean | number | string | MarkdownRef | Text | TextList | PropData[] | {
+type PropData = null | boolean | number | string | MarkdownRef | ImageRef | Text | TextList | PropData[] | {
   [key: string]: PropData;
 };
 ```
@@ -3611,10 +3645,22 @@ interface Ui {
    * Reference a PNG or JPEG file for an `image` property.
    * @capability None.
    * @param path - Absolute path of the image file, inside the package directory or the data directory.
+   * @param options - `maxSide` (SDK 1.5.19, player 0.5.1): decode the image scaled down, aspect kept, so that neither side is over it.
    * @returns A new ImageRef, owned by this scope.
-   * @throws invalid (throws) `path` is not a non-empty string.
+   * @throws invalid (throws) `path` is not a non-empty string, or `maxSide` is not an integer 1–4096.
    */
-  image(path: string): ImageRef;
+  image(path: string, options?: ImageOptions): ImageRef;
+  /**
+   * Download an `https:` PNG or JPEG image (a thumbnail, a repository's plugin icon) and reference the local copy, as Ui.image does.
+   * @capability None (the plugin process has network access).
+   * @player Any (the reference is an ordinary ImageRef); nested in a value, player 0.5.1.
+   * @param url - The image's `https:` address.
+   * @param options - As for Ui.image.
+   * @returns The reference, owned by this scope, once the file is in the cache.
+   * @throws invalid (rejects) `url` is not an `https:` address, or `maxSide` is not an integer 1–4096.
+   * @throws unavailable (rejects) the download failed, timed out, was too large, or is not a PNG or JPEG image; or the plugin has no data directory.
+   */
+  remoteImage(url: string, options?: ImageOptions): Promise<ImageRef>;
   /**
    * Prepare a Markdown document for `MarkdownView` (`@vestra/markdown.slint`).
    * @capability None.
@@ -5181,10 +5227,28 @@ interface Player {
    */
   step(unit: "frame" | "keyframe", direction: "backward" | "forward", options?: Conditional): Promise<void>;
   /**
-   * The core's first-tier relative seek (`seek-backward` / `seek-forward`, ← / →): 0.1–3600 seconds in tenths, default 5. The newest call of any plugin wins; it reverts when that plugin stops.
+   * The core's first-tier relative seek (`seek-backward` / `seek-forward`,
+   * ← / →): 0.1–3600 seconds in tenths, default 5. The newest call of any
+   * plugin wins; it reverts when that plugin stops.
+   *
+   * `keyframes: true` (player 0.5.1, SDK 1.5.19): the step seeks
+   * (`seek-backward` / `seek-forward`, including Host.run with
+   * `seconds` and the picture-in-picture skips) land on a keyframe instead
+   * of the exact time: forward on the first keyframe at or after position +
+   * step, backward on the last at or before position − step, and they
+   * always move. Presses during a seek add up and continue from where it
+   * landed; the on-screen text shows the landed time. Sources without moving
+   * video seek exactly. The seek bar, Player.seek, scrubs, chapters,
+   * loops and Player.step are unaffected. Omitted or `false`: exact
+   * seeks, as before. `seconds` and `keyframes` are written as a pair: the
+   * newest call sets both.
+   *
+   * Older players ignore `keyframes`: set `"minPlayerVersion": "0.5.1"` in
+   * the manifest when you rely on it.
    */
   setStepSeek(options: {
     seconds: number;
+    keyframes?: boolean;
   }): Promise<void>;
   /** The chapters of the current media (empty without media or chapters), read on demand; `sourceId` tells which source they belong to. `playback.read`. */
   chapters(): Promise<{
@@ -5218,23 +5282,29 @@ interface Player {
 
 ### HostAction
 
-The core's basic playback actions (menu commands owned by the player).
+The core's basic playback actions (menu commands owned by the player),
+and the main window's fullscreen toggle.
 
 | action | default bindings | behaviour |
 | --- | --- | --- |
 | `stop` | F4 | close the source |
-| `play-pause` | Space | pause / resume, replay after the end |
+| `play-pause` | Space, a left click on the video (player 0.5.2) | pause / resume, replay after the end |
 | `previous` / `next` | PageUp, Mouse:X1 / PageDown, Mouse:X2 | ask the sequence provider |
 | `frame-back` / `frame-forward` | D / F | `player.step("frame", …)` |
-| `seek-backward` / `seek-forward` | ← / → | relative seek by `setStepSeek` seconds |
+| `seek-backward` / `seek-forward` | ← / → | relative seek by `setStepSeek` seconds (or `host.run`'s `seconds`), exact or to keyframes as `setStepSeek` says |
 | `rate-normal`, `rate-down`, `rate-up` | Z, X, C | 1×, ±0.1 within 0.25–4 |
 | `volume-up` / `volume-down` | ↑ / ↓, wheel | ±5 (`volume-up` stops at 100) |
 | `mute` | M | toggle mute |
+| `fullscreen` | Enter, Alt+Enter, F11 | toggle the main window's fullscreen: enter it when windowed, leave it when fullscreen, as the Toggle Fullscreen command does (SDK 1.5.21, player 0.5.2; `unavailable` when the player has no window) |
 
-In the binding overlay their keys are `host/<action>`.
+In the binding overlay their keys are `host/<action>`. `fullscreen`
+changes no playback state: read the result from `window.state.fullscreen`
+(`plugin.window.onChange`), which also changes when the user toggles it.
+Players before 0.5.2 reject it with `invalid`: set
+`"minPlayerVersion": "0.5.2"` when you use it.
 
 ```ts
-type HostAction = "play-pause" | "stop" | "previous" | "next" | "frame-back" | "frame-forward" | "seek-backward" | "seek-forward" | "rate-down" | "rate-up" | "rate-normal" | "volume-up" | "volume-down" | "mute";
+type HostAction = "play-pause" | "stop" | "previous" | "next" | "frame-back" | "frame-forward" | "seek-backward" | "seek-forward" | "rate-down" | "rate-up" | "rate-normal" | "volume-up" | "volume-down" | "mute" | "fullscreen";
 ```
 
 ### Host
@@ -5252,6 +5322,23 @@ interface Host {
    * Prefer this over reimplementing playback buttons.
    */
   run(action: HostAction): Promise<void>;
+  /**
+   * One step seek of `seconds` (0.1–3600 in tenths) instead of the
+   * Player.setStepSeek step: the same checks, mode (exact or
+   * keyframes), accumulation and on-screen text as ← / →. Use it for more
+   * seek steps of your own (Ctrl+→ and the like) so that they add up with
+   * the core's and land the same way.
+   *
+   * In keyframe mode it resolves once the seek has landed (so
+   * `player.state.position` is current after the `await`); presses that add
+   * up resolve together, the last with the text. In exact mode it resolves
+   * once the seek is submitted, as before. `invalid` for `seconds` out of
+   * range.
+   * @player 0.5.1 (set `"minPlayerVersion": "0.5.1"`: older players ignore `seconds` and seek by the `setStepSeek` step)
+   */
+  run(action: "seek-backward" | "seek-forward", options: {
+    seconds: number;
+  }): Promise<void>;
 }
 ```
 
@@ -6092,6 +6179,23 @@ interface Packages {
    * Stop or start a plugin (`plugins.manage`). An installed plugin stays disabled across launches; a development load only for this run. `invalid` to disable oneself, `missing` unknown. `busy` while it is being installed. `unsupported` to disable a built-in (PluginInfo.builtin): users manage third-party plugins only (players released with SDK 1.5.18 on; older ones disabled built-ins too).
    */
   setEnabled(id: string, enabled: boolean): Promise<void>;
+  /**
+   * Restart a plugin (`plugins.manage`): stop it and start it again from the
+   * same package with the same data directory, for example to recover one
+   * that misbehaves. Built-ins included. A stopped or failed plugin is just
+   * started. The disabled flag is never written, so a reload never leaves
+   * a plugin disabled.
+   *
+   * Resolves once the plugin is stopped and its start is scheduled; the
+   * player starts it as soon as the old process is gone (at most 20 s).
+   * Follow it with Packages.onChange: `starting`, then `running`,
+   * or `failed` with the reason.
+   *
+   * `invalid` for oneself or a disabled plugin (enable it instead),
+   * `missing` unknown, `busy` while it is being installed or reloaded.
+   * @player 0.5.1; older players reject it as an unknown request (`unsupported`).
+   */
+  reload(id: string): Promise<void>;
   /**
    * Remove an installed plugin (`plugins.manage`); `removeData` also deletes its data directory, otherwise reinstalling it from the same source reconnects to its data. Its user bindings stay (as orphans). `unsupported` for built-ins and development loads, `missing` unknown, `invalid` for oneself.
    */
@@ -6991,12 +7095,16 @@ class TestHost implements Transport {
     kind: string;
     title?: string | null;
   }[]): void;
-  /** Runtime images written to views (`plugin.ui.image`), newest last. The SDK refuses images of released scopes before anything is sent. */
+  /**
+   * Runtime images written to views (`plugin.ui.image`, `plugin.ui.remoteImage`), whole values and (SDK 1.5.19) images nested in rows, newest last. The SDK refuses images of released scopes before anything is sent. The test host does not read the files, so it does not check the player's per-view budget (`IMAGE_LIMITS.viewBytes`).
+   */
   readonly images: {
     /** The image file's path, as given to `ui.image`. */
     path: string;
     /** The SDK's reference number for that `ImageRef`. */
     ref: number;
+    /** Its `maxSide` option, when given. */
+    maxSide?: number;
   }[];
   /**
    * The file an image property shows, or `null` when the value is not a runtime image. View properties hold images in their wire form; this reads the path back.
@@ -7317,6 +7425,25 @@ class TestHost implements Transport {
   constructor();
   /** The `player.setStepSeek` value in effect (default 5). */
   stepSeek: number;
+  /** The `player.setStepSeek` `keyframes` in effect (default `false`, SDK 1.5.19). */
+  stepSeekKeyframes: boolean;
+  /**
+   * Test data: the keyframe times (seconds, ascending) of the current source, for keyframe step seeks. `null` (the default): none modelled, and step seeks are exact even with `stepSeekKeyframes`.
+   */
+  keyframes: number[] | null;
+  /**
+   * Every step seek the core ran (`seek-backward` / `seek-forward`, from a key, the menu or `host.run`), newest last: the step, whether it went to a keyframe, and where it landed.
+   */
+  readonly coreSeeks: {
+    /** `seek-backward` or `seek-forward`. */
+    action: string;
+    /** The step: `host.run`'s `seconds`, else `setStepSeek`'s. */
+    seconds: number;
+    /** It landed on a keyframe (`stepSeekKeyframes` and keyframes modelled). */
+    keyframes: boolean;
+    /** The new position. */
+    landed: number;
+  }[];
   /** Every `player.step`, newest last. */
   readonly steps: {
     /** `"frame"` or `"keyframe"`. */
@@ -7430,7 +7557,7 @@ class TestHost implements Transport {
   /** Every `packages.setEnabled` / `uninstall` / `install`, newest last. */
   readonly packageCalls: {
     /** Which call. */
-    method: "setEnabled" | "uninstall" | "install";
+    method: "setEnabled" | "reload" | "uninstall" | "install";
     /** The target plugin id. */
     id: string;
     /** `setEnabled`'s value. */
@@ -7447,7 +7574,7 @@ class TestHost implements Transport {
    */
   readonly candidates: Map<string, PackageManifest>;
   /**
-   * Remote Markdown images (`plugin.ui.markdown`): address → a local PNG or JPEG file served for it, or `null` for a failing download. Nothing is fetched from the network in tests; unknown addresses fail.
+   * Remote images (`plugin.ui.markdown`, `plugin.ui.remoteImage`): address → a local PNG or JPEG file served for it, or `null` for a failing download. Nothing is fetched from the network in tests; unknown addresses fail.
    */
   readonly remoteImages: Map<string, string | null>;
   /**
@@ -7876,6 +8003,25 @@ const UI_VALUE_LIMITS: {
 };
 ```
 
+### IMAGE_LIMITS
+
+The player's runtime image limits (`host/src/ui_image.rs`): a file's
+bytes and sides, the decoded pixels each plugin caches, and (SDK 1.5.19,
+player 0.5.1) the decoded pixels the nested images of one view may show.
+
+```ts
+const IMAGE_LIMITS: Readonly<{
+  /** The largest image file the player reads, in bytes. */
+  fileBytes: number;
+  /** The longest side, in pixels, the player accepts for an image file. */
+  side: 4096;
+  /** The decoded pixel bytes the player caches for each plugin's images. */
+  pluginBytes: number;
+  /** The decoded pixel bytes the nested images of one view may show (player 0.5.1). */
+  viewBytes: number;
+}>;
+```
+
 ### HostError
 
 A definite refusal from the player (or the plugin runner), with a stable
@@ -9594,7 +9740,7 @@ From top to bottom:
 - **The window.** A fixed `width`; `Theme.bg-panel` instead of a hard-coded colour, so the background follows the player's palette.
 - **The properties.** `level` is `in-out` because both the plugin and the user change it; `label` is only written by the plugin. `level-changed` reports a drag; `reset` reports the reset buttons.
 - **The layout.** `Theme.dialog-padding` and `Theme.font-body` give the spacing and text size of the player's dialogs.
-- **`ToolTipArea`** shows its `text` after the pointer rests on its content for 600 ms.
+- **`ToolTipArea`** shows its `text` after the pointer rests on its content for about half a second (600 ms before player 0.5.2). The tip never takes a press or the keyboard focus: a click goes to the control under the pointer even while the tip shows.
 - **The sliders** are bound _two-way_ to `level` with `<=>`, so dragging one moves the other at once, inside Slint. `changed` passes the value to the plugin. A one-way binding (`value: root.level`) would be broken by Slint the first time the user moved the slider. `panel: true` is the panel style; without it, the bar style.
 - **`Button`** with `text` is a dialog button; `small: true` is the 18-pixel one.
 - **Icon buttons** have no `text`; `icon` is SVG-style path data drawn in an `icon-width` × `icon-height` box (14×12 by default). `stroked: true` draws lines instead of filling. `checked` draws the icon in the accent colour.

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.18: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
+> @vestra-player/sdk 1.5.21: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: 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: L2102–2165.
+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: L2120–2184.
 
 **main.ts**
 
@@ -60,7 +60,7 @@ export default async function activate(plugin: Plugin) {
 - `ui.window`: Windows.create
 - `ui.mount`: Panels.mount/bottom/sidebar/backdrop, PanelSlot/Panel/BackdropSlot.onChange
 - `ui.dialog`: Dialogs.confirm/openFile/openFiles/openDirectory/saveFile
-- `plugins.manage`: Packages.validate/validateArchive/setEnabled/uninstall
+- `plugins.manage`: Packages.validate/validateArchive/setEnabled/reload/uninstall
 - `processing.video`: Plugin.video.filter/video.view/video.render (also `playback.read`)
 - `processing.audio`: Plugin.audio.filter (also `playback.read`, `events`)
 - `subtitles.read`: Subtitles.state/onChange/refresh
@@ -76,9 +76,9 @@ export default async function activate(plugin: Plugin) {
 - `ui.settings`: Settings.page/show
 - `ui.theme`: Appearance.set/setLanguage
 - `secrets`: Secrets.get/set/delete
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2166–2208.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2185–2227.
 
-**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` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1588–1753; TestHost: L6751.
+**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` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1606–1771; TestHost: L6855.
 
 **Command line**
 
@@ -106,39 +106,39 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player or another `apiVersion`
-- Others: PluginError, llms-full.txt L3105.
+- Others: PluginError, llms-full.txt L3126.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; the pages are on the [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–214
-- Concepts: How a plugin runs L215–364; Commands, menus and key bindings L365–462; Playback state, controls and sources L463–585; Video and audio processing L586–663; Windows, panels, settings pages, dialogs and the OSD L664–950
-- How-to: Keep a slider responsive while dragging L951–1125; Remember a window's state between runs L1126–1255; Translate a plugin L1256–1439; Migrate a plugin to English source text L1440–1587; Test a plugin L1588–1753; Publish a plugin L1754–1842; Migrating off package rollback (1.5.16, removed in 1.5.17) L1843–1918
-- Guidelines: Interface guidelines L1919–2003; Menu guidelines L2004–2101
-- Reference: Manifest L2102–2165; Capabilities L2166–2208; Limits L2209–2303; Commands, menus and bindings L2304–2772; Platforms L2773–2801; Theme L2802–3006; Command line L3007–3062
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3063–6586
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6587–7909
+- Concepts: How a plugin runs L215–364; Commands, menus and key bindings L365–462; Playback state, controls and sources L463–602; Video and audio processing L603–680; Windows, panels, settings pages, dialogs and the OSD L681–968
+- How-to: Keep a slider responsive while dragging L969–1143; Remember a window's state between runs L1144–1273; Translate a plugin L1274–1457; Migrate a plugin to English source text L1458–1605; Test a plugin L1606–1771; Publish a plugin L1772–1860; Migrating off package rollback (1.5.16, removed in 1.5.17) L1861–1936
+- Guidelines: Interface guidelines L1937–2021; Menu guidelines L2022–2119
+- Reference: Manifest L2120–2184; Capabilities L2185–2227; Limits L2228–2322; Commands, menus and bindings L2323–2791; Platforms L2792–2820; Theme L2821–3027; Command line L3028–3083
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3084–6690
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6691–8055
 
 ## API
 
 Where each module of `plugin` (`plugin.<module>`) is declared:
 
-- Plugin L3297, Scope L3166, PluginError L3105, Disposable L3078
-- Commands L3509; Windows L3714; Panels L4357; Dialogs L4643; Player L5091; video: VideoFilter L5356, VideoView L5419, RenderOptions L5461; audio: AudioFilter L5380; Subtitles L5559; media: MediaCapture L5719; Resolvers L5824; Packages L6066; Osd L5292; Host L5240; Clipboard L6181; Power L6201; Tools L6234; Storage L6277; System L6300; Secrets L6318; window: MainWindow L4480; App L4561; Bindings L6151; Ui L3601; Timeline L4437; Drops L4013; Appearance L4042; I18n L4184; Settings L4290.
+- Plugin L3318, Scope L3187, PluginError L3126, Disposable L3099
+- Commands L3530; Windows L3760; Panels L4403; Dialogs L4689; Player L5137; video: VideoFilter L5443, VideoView L5506, RenderOptions L5548; audio: AudioFilter L5467; Subtitles L5646; media: MediaCapture L5806; Resolvers L5911; Packages L6153; Osd L5379; Host L5310; Clipboard L6285; Power L6305; Tools L6338; Storage L6381; System L6404; Secrets L6422; window: MainWindow L4526; App L4607; Bindings L6255; Ui L3635; Timeline L4483; Drops L4059; Appearance L4088; I18n L4230; Settings L4336.
 
 ## 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. L8333–8422
-- blur: A tool window with one slider that blurs the playing video. L8423–8684
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8685–9017
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9018–9202
-- panel-menu: A sidebar panel with its own right-click menu. L9203–9408
-- menus: Radio menu items, separator groups and a menu item whose title changes. L9409–9568
-- theme-widgets: A tool window drawn with the player's theme and widgets. L9569–9732
-- markdown: A window that shows a Markdown document. L9733–9927
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L9928–10095
+- hello: The README Quick start: one menu command and an on-screen message. L8479–8568
+- blur: A tool window with one slider that blurs the playing video. L8569–8830
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8831–9163
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9164–9348
+- panel-menu: A sidebar panel with its own right-click menu. L9349–9554
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9555–9714
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9715–9878
+- markdown: A window that shows a Markdown document. L9879–10073
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L10074–10241
 
 ## Optional
 

package/package.json

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

package/slint/vestra/icons.slint

@@ -45,6 +45,9 @@ export global Icons {
         if name == "add" { return "M 5 1.5 V 8.5 M 1.5 5 H 8.5"; }
         if name == "remove" { return "M 1.5 5 H 8.5"; }
         if name == "sort" { return "M 3 1.5 V 8.5 M 1.2 6.7 L 3 8.5 L 4.8 6.7 M 7 8.5 V 1.5 M 5.2 3.3 L 7 1.5 L 8.8 3.3"; }
+        // Four corners pointing out (enter) or in (leave), the default 14 × 12 box.
+        if name == "fullscreen" { return "M 1.5 4.5 V 1.5 H 4.5 M 9.5 1.5 H 12.5 V 4.5 M 12.5 7.5 V 10.5 H 9.5 M 4.5 10.5 H 1.5 V 7.5"; }
+        if name == "exit-fullscreen" { return "M 4.5 1.5 V 4.5 H 1.5 M 9.5 1.5 V 4.5 H 12.5 M 12.5 7.5 H 9.5 V 10.5 M 1.5 7.5 H 4.5 V 10.5"; }
         return "";
     }
     // Line width.

package/slint/vestra/widgets.slint

@@ -5,15 +5,20 @@
 import { TextEdit } from "std-widgets.slint";
 import { Theme } from "theme.slint";
 
-// Hover for 600 ms to show `text` beside the pointer. The tip closes when
-// the pointer leaves or presses; it shows again on the next hover.
+// Hover for about half a second to show `text` beside the pointer. The tip
+// closes when the pointer leaves, or presses on content that does not take
+// the press itself; it shows again on the next hover. It is Slint's
+// input-transparent tooltip: every press reaches the control under the
+// pointer, and the tip does not take the keyboard focus. (Up to SDK 1.5.20 the tip was a
+// PopupWindow, which swallowed the first press after it showed and took the
+// focus while it was open.)
 export component ToolTipArea {
     in property <string> text;
-    // The tip is showing (read-only).
+    // The tip is showing (read-only); it follows the tip's delay closely,
+    // not exactly.
     out property <bool> showing;
-    // Shown (or pressed) during this hover: wait for the pointer to leave.
-    // (Never assign the timer's `running`: that drops its binding, and the
-    // tip would show only once.)
+    // Pressed during this hover: no tip until the pointer leaves.
+    // (Never assign the timer's `running`: that drops its binding.)
     private property <bool> done;
     area := TouchArea {
         width: 100%; height: 100%;
@@ -22,40 +27,24 @@ export component ToolTipArea {
             if !self.has-hover {
                 root.done = false;
                 root.showing = false;
-                tip.close();
             }
         }
         pointer-event(event) => {
             if event.kind == PointerEventKind.down {
                 root.done = true;
                 root.showing = false;
-                tip.close();
             }
         }
-    }
-    Timer {
-        interval: 600ms;
-        running: area.has-hover && root.text != "" && !root.done;
-        triggered => {
-            root.done = true;
-            root.showing = true;
-            tip.show();
+        // Removing it closes an open tip.
+        if root.text != "" && !root.done: Tooltip {
+            // Interpolated text is plain: `*` or `_` in it are not markup.
+            text: @markdown("\{root.text}");
         }
     }
-    tip := PopupWindow {
-        x: area.mouse-x + 12px;
-        y: area.mouse-y + 16px;
-        close-policy: close-on-click-outside;
-        Rectangle {
-            background: Theme.bg-panel;
-            border-color: Theme.line;
-            border-width: 1px;
-            border-radius: Theme.radius-control;
-            HorizontalLayout {
-                padding-left: 5px; padding-right: 5px; padding-top: 2px; padding-bottom: 2px;
-                Text { text: root.text; color: Theme.text; font-size: Theme.font-body; }
-            }
-        }
+    Timer {
+        interval: 500ms;
+        running: area.has-hover && root.text != "" && !root.done && !root.showing;
+        triggered => { root.showing = true; }
     }
 }