@vestra-player/sdk 1.5.28 → 1.5.30

package/dist/plugin/bindings.d.ts

@@ -11,12 +11,36 @@ import type { Bindings } from "./types.ts";
  * `"Shift+1"`). Anything else fails with code `invalid`. The player's tests
  * check that these agree with the player.
  *
- * @example
+ * @example Check in a test that the plugin's default keys are well formed
+ * The test fails on a binding the player would refuse with `invalid`, such
+ * as modifiers out of order or a misspelt key name. `isBinding` applies the
+ * same grammar as the player's parser: the part after the last `+` is the
+ * input, everything before it modifiers in the order of `modifiers`; an
+ * input is a listed name or one other printable character, and `Shift`
+ * never goes with a digit or such a character.
  * ```ts
+ * import assert from "node:assert/strict";
  * import { BINDING_INPUTS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(BINDING_INPUTS.named.includes("PageUp"));
- * assert.ok(BINDING_INPUTS.mouse.includes("Mouse:WheelUp"));
+ * const { modifiers, letters, digits, functionKeys, named, mouse } = BINDING_INPUTS;
+ * const names = new Set([...letters, ...functionKeys, ...named, ...mouse]);
+ * function isBinding(binding: string): boolean {
+ *   // "Ctrl++" is not a binding: the + key is written "Plus".
+ *   const parts = binding.split("+");
+ *   const input = parts.pop()!;
+ *   const order = parts.map((m) => (modifiers as readonly string[]).indexOf(m));
+ *   // Each modifier known, at most once, in the listed order.
+ *   if (order.some((at, i) => at < 0 || (i > 0 && at <= order[i - 1]!)))
+ *     return false;
+ *   if (names.has(input)) return true; // letters are upper case: "A"
+ *   const typed = digits.includes(input) || /^[^\p{L}\p{N}\p{C}\s+]$/u.test(input);
+ *   // ">" rather than "Shift+.": the character already says Shift.
+ *   return typed && !parts.includes("Shift");
+ * }
+ * for (const binding of ["Ctrl+Shift+PageUp", "Alt+Mouse:WheelUp", ">"])
+ *   assert.ok(isBinding(binding), binding);
+ * for (const binding of ["Shift+Ctrl+A", "Ctrl+a", "Shift+."])
+ *   assert.ok(!isBinding(binding), binding);
  * ```
  *
  * @since 1.5.14

package/dist/plugin/bindings.js

@@ -18,12 +18,36 @@ import { failure } from "./runtime.js";
  * `"Shift+1"`). Anything else fails with code `invalid`. The player's tests
  * check that these agree with the player.
  *
- * @example
+ * @example Check in a test that the plugin's default keys are well formed
+ * The test fails on a binding the player would refuse with `invalid`, such
+ * as modifiers out of order or a misspelt key name. `isBinding` applies the
+ * same grammar as the player's parser: the part after the last `+` is the
+ * input, everything before it modifiers in the order of `modifiers`; an
+ * input is a listed name or one other printable character, and `Shift`
+ * never goes with a digit or such a character.
  * ```ts
+ * import assert from "node:assert/strict";
  * import { BINDING_INPUTS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(BINDING_INPUTS.named.includes("PageUp"));
- * assert.ok(BINDING_INPUTS.mouse.includes("Mouse:WheelUp"));
+ * const { modifiers, letters, digits, functionKeys, named, mouse } = BINDING_INPUTS;
+ * const names = new Set([...letters, ...functionKeys, ...named, ...mouse]);
+ * function isBinding(binding: string): boolean {
+ *   // "Ctrl++" is not a binding: the + key is written "Plus".
+ *   const parts = binding.split("+");
+ *   const input = parts.pop()!;
+ *   const order = parts.map((m) => (modifiers as readonly string[]).indexOf(m));
+ *   // Each modifier known, at most once, in the listed order.
+ *   if (order.some((at, i) => at < 0 || (i > 0 && at <= order[i - 1]!)))
+ *     return false;
+ *   if (names.has(input)) return true; // letters are upper case: "A"
+ *   const typed = digits.includes(input) || /^[^\p{L}\p{N}\p{C}\s+]$/u.test(input);
+ *   // ">" rather than "Shift+.": the character already says Shift.
+ *   return typed && !parts.includes("Shift");
+ * }
+ * for (const binding of ["Ctrl+Shift+PageUp", "Alt+Mouse:WheelUp", ">"])
+ *   assert.ok(isBinding(binding), binding);
+ * for (const binding of ["Shift+Ctrl+A", "Ctrl+a", "Shift+."])
+ *   assert.ok(!isBinding(binding), binding);
  * ```
  *
  * @since 1.5.14

package/dist/plugin/commands.js

@@ -1,7 +1,8 @@
 /** Menu commands: declaration, state sync (revisions hidden) and dispatch. */
 import { failure, Latest, quiet } from "./runtime.js";
 import { checkBindings } from "./bindings.js";
-import { MENU_IDS } from "../commands.js";
+import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, MENU_IDS } from "../commands.js";
+import { ImageHandle } from "./ui.js";
 import { isTextValue, textProblem } from "../i18n.js";
 const value = (item) => typeof item === "function" ? item() : item;
 /** Validate options and build the wire declaration. */
@@ -32,7 +33,7 @@ function declare(options) {
     if (!Number.isInteger(order) || Math.abs(order) > 1_000_000)
         throw failure("invalid", `command ${options.id}: order must be an integer within ±1000000`);
     const bindings = [...(options.bindings ?? [])];
-    return {
+    const declaration = {
         title: title,
         path: path,
         order,
@@ -42,6 +43,32 @@ function declare(options) {
         focus: options.focus ?? null,
         repeat: options.repeat ?? false,
     };
+    // Only when set: players before 0.5.10 refuse the field.
+    if (options.button !== undefined)
+        declaration.button = button(options.id, options.button, path.length > 0);
+    return declaration;
+}
+/** `CommandOptions.button`, checked as the player checks it, in wire form. */
+function button(id, value, inMenu) {
+    const fail = (problem) => failure("invalid", `command ${id}: ${problem}`);
+    if (value === null || typeof value !== "object")
+        throw fail("button is { icon, order }");
+    if (!inMenu)
+        throw fail("button needs a menu path: a bar button is also a menu item");
+    const { icon, order } = value;
+    if (!Number.isInteger(order) ||
+        order < 0 ||
+        order > BAR_BUTTON_LIMITS.maxOrder)
+        throw fail(`button order must be an integer 0–${BAR_BUTTON_LIMITS.maxOrder}`);
+    if (icon instanceof ImageHandle) {
+        if (icon.released)
+            throw fail(`button image ${icon.path} was released with the scope that created it`);
+        return { icon: icon.toJSON(), order };
+    }
+    if (typeof icon !== "string" ||
+        !BAR_BUTTON_ICONS.includes(icon))
+        throw fail(`unknown button icon ${JSON.stringify(icon)}: a name of @vestra/icons.slint (BAR_BUTTON_ICONS) or an image from plugin.ui.image`);
+    return { icon, order };
 }
 /** Unregistrations in flight per plugin: re-adding an id waits for its removal. */
 const removals = new WeakMap();

package/dist/plugin/osd.d.ts

@@ -8,11 +8,23 @@ import type { TemplateArgsJson, TextValueJson } from "../wire.ts";
  * rejects, `OsdPanel.set` reports to `Scope.onError`. The player's tests
  * check that these agree with the player.
  *
- * @example
+ * @example Keep a long list inside the information block's limits
+ * The block shows the first 32 rows of a list, each cut at 60 columns. The
+ * player counts the text as shown (after it is translated and formatted); a
+ * block over `panelLines` lines or `panelBytes` bytes is refused whole with
+ * `invalid`, reported to `Scope.onError` because `set` never throws, so
+ * the plugin trims the list itself (for very long non-ASCII rows, check the
+ * bytes too).
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const rows: string[];
+ * // ---cut---
  * import { OSD_LIMITS } from "@vestra-player/sdk/testing";
  *
+ * const panel = plugin.osd.panel();
  * const lines = rows.slice(0, OSD_LIMITS.panelLines);
+ * // maxColumns cuts each longer line and ends it with "…".
  * panel.set(lines.join("\n"), null, { maxColumns: 60 });
  * ```
  *

package/dist/plugin/osd.js

@@ -9,11 +9,23 @@ import { isTextValue, textProblem } from "../i18n.js";
  * rejects, `OsdPanel.set` reports to `Scope.onError`. The player's tests
  * check that these agree with the player.
  *
- * @example
+ * @example Keep a long list inside the information block's limits
+ * The block shows the first 32 rows of a list, each cut at 60 columns. The
+ * player counts the text as shown (after it is translated and formatted); a
+ * block over `panelLines` lines or `panelBytes` bytes is refused whole with
+ * `invalid`, reported to `Scope.onError` because `set` never throws, so
+ * the plugin trims the list itself (for very long non-ASCII rows, check the
+ * bytes too).
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const rows: string[];
+ * // ---cut---
  * import { OSD_LIMITS } from "@vestra-player/sdk/testing";
  *
+ * const panel = plugin.osd.panel();
  * const lines = rows.slice(0, OSD_LIMITS.panelLines);
+ * // maxColumns cuts each longer line and ends it with "…".
  * panel.set(lines.join("\n"), null, { maxColumns: 60 });
  * ```
  *

package/dist/plugin/services.d.ts

@@ -13,13 +13,31 @@ export declare function tools(scope: ScopeImpl): Tools;
  * with the key and the request around the value). The player's tests check
  * that these agree with the player.
  *
- * @example
+ * @example Remember a position per URL without breaking the limits
+ * The plugin keeps the last position of each URL for this player session
+ * and skips a URL too long to be a key. Keys are counted in UTF-8 bytes, so
+ * the length is measured with `Buffer.byteLength`, not `length`; a `set`
+ * that would take the plugin's entries over 1 MiB rejects with `limit` and
+ * changes nothing, so the plugin clears the old entries and goes on.
  * ```ts
- * import assert from "node:assert/strict";
+ * import type { Plugin, PluginError } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const url: string;
+ * declare const position: number;
+ * // ---cut---
  * import { SESSION_STORAGE_LIMITS } from "@vestra-player/sdk/testing";
  *
- * const key = "https://example.com/a.mkv";
- * assert.ok(Buffer.byteLength(key) <= SESSION_STORAGE_LIMITS.keyBytes);
+ * const session = plugin.storage.session;
+ * if (Buffer.byteLength(url) <= SESSION_STORAGE_LIMITS.keyBytes) {
+ *   try {
+ *     await session.set(url, position);
+ *   } catch (error) {
+ *     if ((error as PluginError).code !== "limit") throw error;
+ *     // Full: start over rather than lose the newest position.
+ *     for (const key of await session.keys()) await session.delete(key);
+ *     await session.set(url, position);
+ *   }
+ * }
  * ```
  *
  * @since 1.5.25
@@ -46,11 +64,33 @@ export declare function system(scope: ScopeImpl): System;
  * fails with code `invalid`; a new name beyond `names` fails with `limit`.
  * The player's tests check that these agree with the player.
  *
- * @example
+ * @example Store an API token only when it fits
+ * The plugin keeps a token the user pasted, or tells them it is empty or
+ * too long. Values are 1–1024 bytes counted in UTF-8, so the check uses
+ * `Buffer.byteLength`; `secrets.set` would refuse other values with
+ * `invalid`. The store itself can still refuse (`unsupported` without a
+ * system store, `unavailable` or `failed` when it denies access): only
+ * those codes get the "could not be saved" message, anything else (a
+ * missing `secrets` capability) is a bug and is thrown on.
  * ```ts
+ * import type { Plugin, PluginError } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const token: string;
+ * // ---cut---
  * import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(Buffer.byteLength(token) <= SECRET_LIMITS.valueBytes);
+ * if (!token || Buffer.byteLength(token) > SECRET_LIMITS.valueBytes) {
+ *   await plugin.osd.show("Paste a token of at most 1024 bytes.");
+ * } else {
+ *   try {
+ *     await plugin.secrets.set("api-token", token);
+ *   } catch (error) {
+ *     const { code } = error as PluginError;
+ *     if (!["unsupported", "unavailable", "failed"].includes(code)) throw error;
+ *     // No keychain or access denied: ask again next time.
+ *     await plugin.osd.show("The token could not be saved.");
+ *   }
+ * }
  * ```
  *
  * @since 1.5.14

package/dist/plugin/services.js

@@ -247,13 +247,31 @@ class Store {
  * with the key and the request around the value). The player's tests check
  * that these agree with the player.
  *
- * @example
+ * @example Remember a position per URL without breaking the limits
+ * The plugin keeps the last position of each URL for this player session
+ * and skips a URL too long to be a key. Keys are counted in UTF-8 bytes, so
+ * the length is measured with `Buffer.byteLength`, not `length`; a `set`
+ * that would take the plugin's entries over 1 MiB rejects with `limit` and
+ * changes nothing, so the plugin clears the old entries and goes on.
  * ```ts
- * import assert from "node:assert/strict";
+ * import type { Plugin, PluginError } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const url: string;
+ * declare const position: number;
+ * // ---cut---
  * import { SESSION_STORAGE_LIMITS } from "@vestra-player/sdk/testing";
  *
- * const key = "https://example.com/a.mkv";
- * assert.ok(Buffer.byteLength(key) <= SESSION_STORAGE_LIMITS.keyBytes);
+ * const session = plugin.storage.session;
+ * if (Buffer.byteLength(url) <= SESSION_STORAGE_LIMITS.keyBytes) {
+ *   try {
+ *     await session.set(url, position);
+ *   } catch (error) {
+ *     if ((error as PluginError).code !== "limit") throw error;
+ *     // Full: start over rather than lose the newest position.
+ *     for (const key of await session.keys()) await session.delete(key);
+ *     await session.set(url, position);
+ *   }
+ * }
  * ```
  *
  * @since 1.5.25
@@ -390,11 +408,33 @@ export function system(scope) {
  * fails with code `invalid`; a new name beyond `names` fails with `limit`.
  * The player's tests check that these agree with the player.
  *
- * @example
+ * @example Store an API token only when it fits
+ * The plugin keeps a token the user pasted, or tells them it is empty or
+ * too long. Values are 1–1024 bytes counted in UTF-8, so the check uses
+ * `Buffer.byteLength`; `secrets.set` would refuse other values with
+ * `invalid`. The store itself can still refuse (`unsupported` without a
+ * system store, `unavailable` or `failed` when it denies access): only
+ * those codes get the "could not be saved" message, anything else (a
+ * missing `secrets` capability) is a bug and is thrown on.
  * ```ts
+ * import type { Plugin, PluginError } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const token: string;
+ * // ---cut---
  * import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(Buffer.byteLength(token) <= SECRET_LIMITS.valueBytes);
+ * if (!token || Buffer.byteLength(token) > SECRET_LIMITS.valueBytes) {
+ *   await plugin.osd.show("Paste a token of at most 1024 bytes.");
+ * } else {
+ *   try {
+ *     await plugin.secrets.set("api-token", token);
+ *   } catch (error) {
+ *     const { code } = error as PluginError;
+ *     if (!["unsupported", "unavailable", "failed"].includes(code)) throw error;
+ *     // No keychain or access denied: ask again next time.
+ *     await plugin.osd.show("The token could not be saved.");
+ *   }
+ * }
  * ```
  *
  * @since 1.5.14