@vestra-player/sdk 1.5.13 → 1.5.15

package/dist/plugin/types.d.ts

@@ -81,6 +81,19 @@ export interface Disposable {
  * | `host` | Any other failure inside the player; `message` is the player's reason. |
  * | `disabled` | The plugin is being stopped; pending requests fail with it. |
  * | `unknown`, `rejected`, `expired` | After a transport problem the SDK could not confirm the outcome (does not happen in normal operation). |
+ * | `activation` | The plugin opened a tool window while its activation was still pending and the player could not track it. |
+ * | `command` | The player could not run or update a command it no longer knows for this plugin (removed meanwhile, or another plugin's). |
+ * | `input-overflow` | `openStream` input: the player's queue of physical key transitions was full; the input was revoked and its keys released. |
+ * | `internal` | An internal step of the player failed (keeping an operation's result, a subtitle or media job); `message` has the reason. |
+ * | `javascript`, `slint` | {@link Packages.validate}: the package's entry module does not pass `node --check` / one of its Slint files does not compile; `message` has the diagnostics. |
+ * | `owner` | A resolver answered a request that belongs to another plugin's resolver. |
+ * | `pending` | An operation with the same token is still running in the player. The SDK waits and asks again, so it rarely reaches a plugin. |
+ * | `producer` | `openStream`: the player refused or lost the generated stream; `message` has the reason. |
+ * | `resolution` | A file or web resolver's result could not be opened; `message` has the reason. |
+ * | `revisionConflict` | {@link Packages}: the installed revision changed since it was read (another install, rollback or uninstall ran). Read again and retry; the SDK passes the revision it read, so this reaches plugins that act on old data. |
+ * | `source-geometry`, `source-geometry-unsupported` | The source's picture size or rotation could not be applied: invalid decoder dimensions / a rotation that is not a multiple of 90°. |
+ * | `source-unavailable` | The source is not ready (still loading, or its time or native binding is not available yet). |
+ * | `unknown-expired` | The player no longer knows the operation or snapshot (it expired or was released). The SDK maps it to `unknownExpired` results where it can; do not resubmit the operation blindly. |
  *
  * Errors thrown by handlers the SDK invokes go to {@link Scope.onError}. A
  * rejected promise you forgot to `await` is only logged; it never crashes
@@ -320,16 +333,19 @@ export interface Plugin extends Scope {
     /** The manifest id, e.g. `"community.bookmark"`. */
     readonly id: string;
     /**
-     * A writable directory for this plugin's own files (settings, remembered
-     * folders). Kept across restarts, disabling and upgrades. Write files atomically: to a temporary name, then rename.
-     * Throws `unavailable` when the player provided none.
+     * A writable directory for this plugin's own files (settings, caches,
+     * remembered folders), created by the player before it starts the plugin.
+     * Each installation has its own directory (player 0.2.0): it is kept across
+     * restarts, disabling, upgrades and rollbacks, and a reinstall of the same
+     * id from a different source gets a new, empty one. It is deleted only by
+     * `packages.uninstall(id, { removeData: true })`. No capability.
      *
-     * Location: `~/Library/Application Support/Vestra/plugin-data/<id>/` on
-     * macOS, `%APPDATA%\Vestra\plugin-data\<id>\` on Windows (the environment
-     * variable `VESTRA_PLUGIN_DATA` moves the root). Another plugin's data
-     * directory is `join(dirname(plugin.dataDirectory), id)`. It is deleted
-     * only by `packages.uninstall(id, { removeData: true })`. No capability.
-     * For JSON settings prefer {@link Scope.storage}.
+     * The path's format is not part of the API: do not derive another
+     * plugin's directory from it (a plugin manager reads
+     * {@link PluginInfo.dataDirectory}). Write files atomically (to a
+     * temporary name, then rename); for JSON settings prefer
+     * {@link Scope.storage}. Throws `unavailable` when the player provided
+     * none. See [How a plugin runs](../../docs/concepts/plugins.md#the-data-directory).
      */
     readonly dataDirectory: string;
 }
@@ -388,9 +404,10 @@ export type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "sc
  * item never moves the player's menu. Directly inside a built-in menu,
  * `order` 0 (the default) sorts after every other order: an item without
  * `order` goes at the end, after the player's own items (which all use 100
- * or more). Give a positive order to sit between them (the player's orders
- * are listed in its menu table, doc/product/menus.md), or a negative one to
- * come first. Deeper levels (a plugin's own submenu) have no such rule.
+ * or more). Give a positive order to sit between them (the player's items
+ * in menu order are in
+ * [Built-in commands](../../docs/reference/commands.md#built-in-commands)),
+ * or a negative one to come first. Deeper levels (a plugin's own submenu) have no such rule.
  * Players before 0.3.0 place every submenu at its smallest order, so there
  * an item without `order` moves the whole menu to the top; to avoid that,
  * give it an order in the menu's range (Video: 400–499).
@@ -471,8 +488,8 @@ export interface CommandOptions {
      *
      * Platforms: on macOS `Ctrl+X` fires for both ⌃X and ⌘X while `Cmd+X`
      * means ⌘X only; on Windows `Cmd` is the Windows logo key, so write
-     * `Ctrl+…` for bindings that work on both. Avoid keys the system takes
-     * first (⌃F1–⌃F8, ⌃Arrow keys, ⌘Tab on macOS).
+     * `Ctrl+…` for bindings that work on both. Avoid the
+     * [keys the system takes first](../../docs/reference/commands.md#keys-the-system-takes-first).
      *
      * Conflicts are not errors: the user's overrides win, then the player's
      * own commands, then the plugin loaded first; a shadowed binding takes
@@ -812,6 +829,15 @@ export interface Ui {
      * The text is at most 256 KB; very long documents are cut off after 4000
      * blocks.
      *
+     * `MarkdownView` scrolls one document. `MarkdownBlocks` (SDK 1.5.4, players
+     * after 0.4.0) draws one without scrolling, as tall as its content, for a
+     * layout of your own or a `ListView` row. For a list of documents, write
+     * the whole list with one document per row: the player parses only the
+     * documents that changed and updates the list in place (rows added or
+     * removed at the end, a growing document's changed blocks), so re-sending
+     * the list on every streamed chunk keeps the scroll position and costs
+     * little.
+     *
      * @capability None.
      * @player 0.2.0 (set `"minPlayerVersion": "0.2.0"` in the manifest)
      *
@@ -826,6 +852,44 @@ export interface Ui {
      *   `base` is neither an `http(s):` address nor an absolute path.
      * @throws `unsupported` (rejects) The player is older than 0.2.0.
      *
+     * @example A chat: one Markdown document per row, with Copy buttons
+     * `ui/chat.slint`:
+     *
+     * ```slint
+     * import { ListView } from "std-widgets.slint";
+     * import { MarkdownBlocks, MarkdownBlock } from "@vestra/markdown.slint";
+     * export struct Message { id: string, role: string, body: [MarkdownBlock] }
+     * export component Chat inherits Window {
+     *     in property <[Message]> messages;
+     *     callback copy-code(string);
+     *     ListView {
+     *         for message in root.messages: VerticalLayout {
+     *             padding: 8px;
+     *             MarkdownBlocks {
+     *                 blocks: message.body;
+     *                 code-copy: true;
+     *                 copy-code(code) => { root.copy-code(code); }
+     *             }
+     *         }
+     *     }
+     * }
+     * ```
+     *
+     * ```ts
+     * const chat = plugin.windows.create("ui/chat.slint");
+     * const history: { id: string; role: string; text: string }[] = [];
+     * chat.on("copyCode", (code: string) => plugin.clipboard.writeText(code));
+     * async function render() {
+     *   const messages = [];
+     *   for (const { id, role, text } of history)
+     *     messages.push({ id, role, body: await plugin.ui.markdown(text) });
+     *   chat.set({ messages });
+     * }
+     * history.push({ id: "1", role: "user", text: "Show me `ls`." });
+     * await render();
+     * await chat.show();
+     * ```
+     *
      * @example Show a README from the web
      * ```ts
      * const readmeUrl = "https://example.com/plugin/README.md";
@@ -1029,8 +1093,8 @@ export interface View {
  *    {@link View.bind} or {@link View.set}.
  * 3. {@link Window.show} opens the window with those properties.
  *    {@link Window.hide} hides it and keeps its state.
- * 4. {@link Window.close}, or the user (title-bar button; ⌘W on macOS,
- *    Ctrl+W or Ctrl+F4 on Windows), destroys the window instance; only the
+ * 4. {@link Window.close}, or the user (title-bar button or the
+ *    [standard close keys](../../docs/reference/commands.md#keys-the-system-takes-first)), destroys the window instance; only the
  *    user's close calls {@link Window.onClose}. The handle stays usable: the
  *    next `show()` opens a fresh instance with the current properties.
  * 5. `dispose()`, disposing the owning scope or the plugin stopping closes
@@ -1184,8 +1248,8 @@ export interface Window extends View, Disposable {
      * Run code when the user closes the window.
      *
      * @remarks
-     * Called for the title-bar close button and the standard close keys (⌘W
-     * on macOS, Ctrl+W or Ctrl+F4 on Windows). When it runs, the window
+     * Called for the title-bar close button and the
+     * [standard close keys](../../docs/reference/commands.md#keys-the-system-takes-first). When it runs, the window
      * instance is gone and {@link Window.opened} is already `false`; a later
      * `show()` opens a fresh one. It is not called for the plugin's own
      * {@link Window.close} or `dispose()`, nor when the plugin stops. Errors
@@ -1294,8 +1358,10 @@ export interface SlotState {
      * - `fullscreen`: the sidebar's fullscreen overlay is collapsed and pops
      *   out when the pointer reaches the right edge; treat it as "on" for a
      *   toggle button;
-     * - `idle`: the bottom bar in fullscreen, hidden after 3 seconds without
-     *   activity.
+     * - `idle`: the bottom bar in fullscreen while the pointer is outside the
+     *   bar's own band at the bottom of the screen (player 0.5.1: keys and
+     *   pointer motion elsewhere do not bring it back; before 0.5.1 it hid after
+     *   3 seconds without activity).
      */
     reason: "userHidden" | "space" | "fullscreen" | "idle" | null;
     /** The sidebar floats in its own window; always `false` for the bottom bar. */
@@ -1514,8 +1580,8 @@ export interface PanelSlot {
  * Detached, the sidebar panel is shown in a separate window (300×408 by
  * default, at least 300×250) with the panel's `title`. The plugin's
  * properties and callbacks stay the same, but the window holds a new
- * instance of the component. Closing the floating window (its close button,
- * ⌘W, Ctrl+W, Ctrl+F4) is the same as `setVisible(false)`.
+ * instance of the component. Closing the floating window (its close button
+ * or the [standard close keys](../../docs/reference/commands.md#keys-the-system-takes-first)) is the same as `setVisible(false)`.
  *
  * @capability ui.mount
  *
@@ -1732,8 +1798,11 @@ export interface Panel extends View, Disposable {
      * Keep the panel on screen while the user works in it.
      *
      * @remarks
-     * The bottom bar hides after 3 seconds without activity in fullscreen, and
-     * the fullscreen sidebar overlay collapses when the pointer leaves it. Set a
+     * In fullscreen the bottom bar shows only while the pointer is in the bar's
+     * own band at the bottom of the screen: at once when the pointer enters it,
+     * hidden 500 ms after it leaves (player 0.5.1; keys and pointer motion
+     * elsewhere do not reveal it), and the fullscreen sidebar overlay collapses
+     * when the pointer leaves it. A lock keeps the bar shown. Set a
      * lock while a text field has focus, a drag is in progress or a popup is
      * open, and clear it afterwards. Locks are merged with the earlier ones;
      * the last value of each wins. The player already locks a panel while the
@@ -2645,7 +2714,9 @@ export interface Panels {
      * - `"bottom"`: under the video, as wide as the video column, as tall as the
      *   component's preferred height. It may draw above its slot into the video
      *   area (negative `y`); the player does not clip it. In fullscreen it
-     *   floats over the video and hides after 3 seconds without activity.
+     *   floats over the video and shows only while the pointer is in its band
+     *   at the bottom of the screen (hidden 500 ms after the pointer leaves;
+     *   {@link Panel.setInteraction} locks keep it).
      * - `"sidebar"`: right of the video, the window's full height, as wide as the
      *   user drags it (at least 317). The user can detach it into a floating
      *   window titled `title`. Several plugins may mount here (player 0.4.x
@@ -3440,10 +3511,27 @@ export interface PlaybackStats {
     backend: string;
     /** The playback session number. */
     session: number;
-    /** Frames the host has shown. */
+    /**
+     * Frames the video renderer produced. Not all of them reach the screen: a
+     * busy window shows only the newest one, so compare
+     * {@link PlaybackStats.presentedFps | presentedFps}.
+     */
     framesShown: number;
-    /** Frames dropped, `null` when unknown. */
+    /** Frames dropped by the backend (mpv), `null` when unknown. */
     framesDropped: number | null;
+    /**
+     * New video frames the player window showed per second over the last
+     * second, measured by the player itself: draws of the main window that put
+     * a new picture on screen. Lower than `video.fps` when frames are lost
+     * after decoding and rendering (the window could not keep up with the
+     * source, or the display refreshes slower); `0` while paused. `null` when
+     * the player cannot measure it (no window, the first second, players
+     * before 0.5.1).
+     *
+     * @player 0.5.1
+     * @since 1.5.15
+     */
+    presentedFps: number | null;
     /** Every field is the backend's own value, `null` when it has none. */
     video: {
         /** Codec name. */
@@ -3468,8 +3556,15 @@ export interface PlaybackStats {
         displayFps: number | null;
         /** Bits per second, updated per keyframe. */
         bitrate: number | null;
-        /** Hardware decoder in use, e.g. "videotoolbox"; "no" = software decoding. */
+        /** Hardware decoder in use, e.g. "videotoolbox", "d3d11va-copy"; "no" = software decoding. */
         hwdec: string | null;
+        /**
+         * How the video is decoded, from `hwdec`: `"hardware"` (the method is in
+         * `hwdec`) or `"software"`; `null` before a decoder runs.
+         *
+         * @since 1.5.15 (with older players the SDK derives it from `hwdec`)
+         */
+        decoding: "hardware" | "software" | null;
         /** Transfer characteristic as mpv names it, e.g. "bt.1886", "pq", "hlg". */
         transfer: string | null;
     } | null;
@@ -3714,8 +3809,8 @@ export interface Host {
  * {@link Osd.panel}.
  *
  * @remarks
- * The block sits under the OSD message line, on a translucent black
- * background, and takes no input. Its font scales with the video area. When
+ * The block sits under the OSD message line, on a translucent dark plate
+ * (see {@link Osd} for sizes), and takes no input. When
  * several plugins have one, they are stacked from top to bottom. `dispose()`,
  * disposing the scope or stopping the plugin removes it.
  *
@@ -3789,8 +3884,25 @@ export interface OsdPanelOptions {
  * ({@link Osd.show}) is one line at the top left of the video that
  * disappears after 2 seconds; a newer message, from any plugin, replaces it.
  * The information block ({@link Osd.panel}) stays until the plugin changes
- * or removes it. Both are white text with a dark outline whose size follows
- * the height of the video area.
+ * or removes it.
+ *
+ * How the player draws them (a player before 0.4.0 drew bold white text
+ * with a black outline instead):
+ *
+ * - **Message**: white text on a translucent dark plate with rounded
+ *   corners and a gradient line along its bottom edge, 10px from the
+ *   video area's left and top edges.
+ * - **Font size** follows the video area: 3 % of its height, rounded and
+ *   clamped to 12–48px (about 18px in the default window, 32px in
+ *   fullscreen at 1080 pixels high). The plate's padding and corners scale
+ *   with it.
+ * - **Information block**: 4px below the message plate, on the same kind of
+ *   plate; its font scales in proportion (11px when the message is 16px),
+ *   clamped to 9–28px.
+ *
+ * How long a text may be is in
+ * [Limits: on-screen display](../../docs/reference/limits.md#on-screen-display)
+ * ({@link "@vestra-player/sdk/testing"!OSD_LIMITS | OSD_LIMITS}).
  *
  * @capability ui.osd
  *

package/dist/subtitles.d.ts

@@ -45,7 +45,11 @@ export type SubtitleStyle = {
     outline: number;
     /** Bottom margin 2–15 % of the video height. */
     marginPercent: number;
-    /** Timing offset −600000–600000 ms. */
+    /**
+     * Timing offset in milliseconds, −600000…600000 (±10 minutes); positive
+     * shows the subtitles later. Outside the range the player refuses the
+     * style with `invalid`.
+     */
     offsetMs: number;
     /** Bold text; default false. */
     bold?: boolean;

package/dist/wire.d.ts

@@ -222,6 +222,8 @@ export interface PlaybackStats {
     session: number;
     framesShown: number;
     framesDropped: number | null;
+    /** Player 0.5.1 and newer; the SDK fills in `null`. */
+    presentedFps?: number | null;
     video: {
         codec: string | null;
         width: number | null;
@@ -235,6 +237,7 @@ export interface PlaybackStats {
         displayFps?: number | null;
         bitrate?: number | null;
         hwdec?: string | null;
+        decoding?: "hardware" | "software" | null;
         transfer?: string | null;
     } | null;
     audio: {