@vestra-player/sdk 1.5.13 → 1.5.15

package/dist/plugin/bindings.js

@@ -7,54 +7,103 @@
  *   input    = key | "Mouse:" mouse
  */
 import { failure } from "./runtime.js";
-const MODIFIERS = ["Ctrl", "Alt", "Shift", "Cmd"];
+/**
+ * The names a binding (`CommandOptions.bindings`, `Bindings.set`) is made
+ * of, as the player's binding parser accepts them. A binding is
+ * `{ modifier "+" } input`: modifiers in the order of `modifiers`, each at
+ * most once, then one input. An input is a name of `letters`, `digits`,
+ * `functionKeys`, `named` or `mouse`, or one other printable character that
+ * is not a letter, digit, space or `+` (`">"`, `"["`, `"/"`), written as
+ * typed, never with `Shift` (`">"`, not `"Shift+."`; `"!"`, not
+ * `"Shift+1"`). Anything else fails with code `invalid`. The player's tests
+ * check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { BINDING_INPUTS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(BINDING_INPUTS.named.includes("PageUp"));
+ * assert.ok(BINDING_INPUTS.mouse.includes("Mouse:WheelUp"));
+ * ```
+ *
+ * @since 1.5.14
+ */
+export const BINDING_INPUTS = Object.freeze({
+    /**
+     * Modifiers, in the order a binding writes them. `Cmd` is ⌘ on macOS and
+     * the Windows logo key on Windows; on macOS `Ctrl` also matches ⌘.
+     */
+    modifiers: ["Ctrl", "Alt", "Shift", "Cmd"],
+    /** Letter keys, by key name whatever the case: `A` to `Z`. */
+    letters: [..."ABCDEFGHIJKLMNOPQRSTUVWXYZ"],
+    /** Digit keys of the main keyboard: `0` to `9`. */
+    digits: [..."0123456789"],
+    /** Function keys: `F1` to `F24`. */
+    functionKeys: Array.from({ length: 24 }, (_, index) => `F${index + 1}`),
+    /**
+     * Other named keys, matched by the physical key. `Plus` is the `+` key
+     * however it is typed; the `Numpad…` names are the numeric keypad only,
+     * never the main keyboard.
+     */
+    named: [
+        "Space",
+        "Enter",
+        "Tab",
+        "Escape",
+        "Backspace",
+        "Delete",
+        "Insert",
+        "Home",
+        "End",
+        "PageUp",
+        "PageDown",
+        "ArrowLeft",
+        "ArrowRight",
+        "ArrowUp",
+        "ArrowDown",
+        "Plus",
+        ...Array.from({ length: 10 }, (_, digit) => `Numpad${digit}`),
+        "NumpadPlus",
+        "NumpadMinus",
+        "NumpadMultiply",
+        "NumpadDivide",
+        "NumpadEnter",
+        "NumpadDecimal",
+    ],
+    /**
+     * Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the
+     * halves of the video apart for a double click.
+     */
+    mouse: [
+        "Mouse:LeftClick",
+        "Mouse:LeftDoubleClick",
+        "Mouse:LeftDoubleClick:LeftHalf",
+        "Mouse:LeftDoubleClick:RightHalf",
+        "Mouse:MiddleClick",
+        "Mouse:X1",
+        "Mouse:X2",
+        "Mouse:WheelUp",
+        "Mouse:WheelDown",
+        "Mouse:WheelLeft",
+        "Mouse:WheelRight",
+    ],
+});
+const MODIFIERS = BINDING_INPUTS.modifiers;
 const NAMED = new Set([
-    "Space",
-    "Enter",
-    "Tab",
-    "Escape",
-    "Backspace",
-    "Delete",
-    "Insert",
-    "Home",
-    "End",
-    "PageUp",
-    "PageDown",
-    "ArrowLeft",
-    "ArrowRight",
-    "ArrowUp",
-    "ArrowDown",
-    "Plus",
-    // Numeric keypad: never matched by the main keyboard keys, nor they by these.
-    ..."0123456789".split("").map((digit) => `Numpad${digit}`),
-    "NumpadPlus",
-    "NumpadMinus",
-    "NumpadMultiply",
-    "NumpadDivide",
-    "NumpadEnter",
-    "NumpadDecimal",
-]);
-const MOUSE = new Set([
-    "LeftClick",
-    "LeftDoubleClick",
-    "LeftDoubleClick:LeftHalf",
-    "LeftDoubleClick:RightHalf",
-    "MiddleClick",
-    "X1",
-    "X2",
-    "WheelUp",
-    "WheelDown",
-    "WheelLeft",
-    "WheelRight",
+    ...BINDING_INPUTS.functionKeys,
+    ...BINDING_INPUTS.named,
 ]);
+const MOUSE = new Set(BINDING_INPUTS.mouse);
+const LETTERS = new Set(BINDING_INPUTS.letters);
+const DIGITS = new Set(BINDING_INPUTS.digits);
 function kind(input) {
     if (input.startsWith("Mouse:"))
-        return MOUSE.has(input.slice(6)) ? "mouse" : null;
-    if (/^[A-Z]$/.test(input))
+        return MOUSE.has(input) ? "mouse" : null;
+    if (LETTERS.has(input))
         return "letter";
-    if (/^[0-9]$/.test(input))
+    if (DIGITS.has(input))
         return "digit";
-    if (/^F([1-9]|1[0-9]|2[0-4])$/.test(input) || NAMED.has(input))
+    if (NAMED.has(input))
         return "named";
     // One printable, non-alphanumeric, non-space character; "+" is written Plus.
     if ([...input].length === 1 && /^[^\p{L}\p{N}\s+]$/u.test(input))

package/dist/plugin/osd.d.ts

@@ -1,6 +1,38 @@
 import type { ScopeImpl } from "./scope.ts";
 import type { Osd } from "./types.ts";
 import type { TemplateArgsJson, TextValueJson } from "../wire.ts";
+/**
+ * The player's limits on the on-screen display ({@link Osd}), counted on
+ * the text as shown: after the player translated it and filled in its
+ * arguments. A text over them fails with code `invalid`: `osd.show`
+ * rejects, `OsdPanel.set` reports to `Scope.onError`. The player's tests
+ * check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { OSD_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * const lines = rows.slice(0, OSD_LIMITS.panelLines);
+ * panel.set(lines.join("\n"), null, { maxColumns: 60 });
+ * ```
+ *
+ * @since 1.5.14
+ */
+export declare const OSD_LIMITS: Readonly<{
+    /**
+     * Characters of one `osd.show` message (200; at least 1 that is not
+     * white space). Line breaks are shown as spaces.
+     */
+    readonly messageChars: 200;
+    /** Lines of the information block (`OsdPanel.set`) (32). */
+    readonly panelLines: 32;
+    /** UTF-8 bytes of the information block (4096). */
+    readonly panelBytes: 4096;
+    /** The smallest `OsdPanelOptions.maxColumns` (8). */
+    readonly minColumns: 8;
+    /** The largest `OsdPanelOptions.maxColumns` (1000). */
+    readonly maxColumns: 1000;
+}>;
 /**
  * Copy and check template arguments: an array or object of at most 16
  * strings, finite numbers, texts and lists (`TEXT_LIMITS`).

package/dist/plugin/osd.js

@@ -2,6 +2,38 @@
 import { Latest } from "./runtime.js";
 import { failure } from "./runtime.js";
 import { isTextValue, textProblem } from "../i18n.js";
+/**
+ * The player's limits on the on-screen display ({@link Osd}), counted on
+ * the text as shown: after the player translated it and filled in its
+ * arguments. A text over them fails with code `invalid`: `osd.show`
+ * rejects, `OsdPanel.set` reports to `Scope.onError`. The player's tests
+ * check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { OSD_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * const lines = rows.slice(0, OSD_LIMITS.panelLines);
+ * panel.set(lines.join("\n"), null, { maxColumns: 60 });
+ * ```
+ *
+ * @since 1.5.14
+ */
+export const OSD_LIMITS = Object.freeze({
+    /**
+     * Characters of one `osd.show` message (200; at least 1 that is not
+     * white space). Line breaks are shown as spaces.
+     */
+    messageChars: 200,
+    /** Lines of the information block (`OsdPanel.set`) (32). */
+    panelLines: 32,
+    /** UTF-8 bytes of the information block (4096). */
+    panelBytes: 4096,
+    /** The smallest `OsdPanelOptions.maxColumns` (8). */
+    minColumns: 8,
+    /** The largest `OsdPanelOptions.maxColumns` (1000). */
+    maxColumns: 1000,
+});
 /**
  * Copy and check template arguments: an array or object of at most 16
  * strings, finite numbers, texts and lists (`TEXT_LIMITS`).
@@ -54,8 +86,10 @@ class PanelHandle {
         try {
             const max = options?.maxColumns;
             if (max !== undefined &&
-                !(Number.isInteger(max) && max >= 8 && max <= 1000))
-                throw failure("invalid", "maxColumns is an integer from 8 to 1000");
+                !(Number.isInteger(max) &&
+                    max >= OSD_LIMITS.minColumns &&
+                    max <= OSD_LIMITS.maxColumns))
+                throw failure("invalid", `maxColumns is an integer from ${OSD_LIMITS.minColumns} to ${OSD_LIMITS.maxColumns}`);
             value = {
                 text: text === null ? null : shownText(text, args),
                 ...(text === null || args === undefined || args === null

package/dist/plugin/player.js

@@ -81,6 +81,12 @@ function view(raw) {
     raws.set(state, raw);
     return state;
 }
+/** `stats().video.decoding` from `hwdec` for players that do not send it. */
+function decoding(hwdec) {
+    if (hwdec === null || hwdec === undefined || hwdec === "")
+        return null;
+    return hwdec === "no" ? "software" : "hardware";
+}
 export const rawOf = (state) => raws.get(state);
 export const sameStamp = (a, b) => a.generation === b.generation && a.intentVersion === b.intentVersion;
 function sourceFailure(error) {
@@ -474,6 +480,7 @@ export function player(scope) {
                 session: raw.session,
                 framesShown: raw.framesShown,
                 framesDropped: raw.framesDropped,
+                presentedFps: n(raw.presentedFps),
                 video: raw.video && {
                     codec: raw.video.codec,
                     width: raw.video.width,
@@ -487,6 +494,7 @@ export function player(scope) {
                     displayFps: n(raw.video.displayFps),
                     bitrate: n(raw.video.bitrate),
                     hwdec: n(raw.video.hwdec),
+                    decoding: raw.video.decoding ?? decoding(raw.video.hwdec),
                     transfer: n(raw.video.transfer),
                 },
                 audio: raw.audio && {

package/dist/plugin/services.d.ts

@@ -6,4 +6,29 @@ export declare const power: (scope: ScopeImpl) => Power;
 export declare function tools(scope: ScopeImpl): Tools;
 export declare const storage: (scope: ScopeImpl) => Storage;
 export declare function system(scope: ScopeImpl): System;
+/**
+ * The player's limits on {@link Secrets}. A name or value outside them
+ * fails with code `invalid`; a new name beyond `names` fails with `limit`.
+ * The player's tests check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(Buffer.byteLength(token) <= SECRET_LIMITS.valueBytes);
+ * ```
+ *
+ * @since 1.5.14
+ */
+export declare const SECRET_LIMITS: Readonly<{
+    /**
+     * Characters of a name (64, at least 1), each one of `a-z`, `0-9`, `.`,
+     * `_` and `-`.
+     */
+    readonly nameChars: 64;
+    /** UTF-8 bytes of a value (1024, at least 1; no NUL character). */
+    readonly valueBytes: 1024;
+    /** Different names one plugin may have stored at the same time (256). */
+    readonly names: 256;
+}>;
 export declare const secrets: (scope: ScopeImpl) => Secrets;

package/dist/plugin/services.js

@@ -292,13 +292,38 @@ export function system(scope) {
         },
     };
 }
-const SECRET = /^[a-z0-9._-]{1,64}$/;
+/**
+ * The player's limits on {@link Secrets}. A name or value outside them
+ * fails with code `invalid`; a new name beyond `names` fails with `limit`.
+ * The player's tests check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(Buffer.byteLength(token) <= SECRET_LIMITS.valueBytes);
+ * ```
+ *
+ * @since 1.5.14
+ */
+export const SECRET_LIMITS = Object.freeze({
+    /**
+     * Characters of a name (64, at least 1), each one of `a-z`, `0-9`, `.`,
+     * `_` and `-`.
+     */
+    nameChars: 64,
+    /** UTF-8 bytes of a value (1024, at least 1; no NUL character). */
+    valueBytes: 1024,
+    /** Different names one plugin may have stored at the same time (256). */
+    names: 256,
+});
+const SECRET = new RegExp(`^[a-z0-9._-]{1,${SECRET_LIMITS.nameChars}}$`);
 export const secrets = (scope) => {
     const named = (name) => {
         if (!scope.runtime.can("secrets"))
             throw failure("capability", "secrets must be declared in manifest");
         if (typeof name !== "string" || !SECRET.test(name))
-            throw failure("invalid", "secret names are 1–64 of a-z, 0-9, ., _ and -");
+            throw failure("invalid", `secret names are 1–${SECRET_LIMITS.nameChars} of a-z, 0-9, ., _ and -`);
         return name;
     };
     return {
@@ -307,8 +332,8 @@ export const secrets = (scope) => {
             if (typeof value !== "string" ||
                 !value ||
                 value.includes("\0") ||
-                Buffer.byteLength(value) > 1024)
-                throw failure("invalid", "secret values are 1–1024 bytes of text; delete() removes one");
+                Buffer.byteLength(value) > SECRET_LIMITS.valueBytes)
+                throw failure("invalid", `secret values are 1–${SECRET_LIMITS.valueBytes} bytes of text; delete() removes one`);
             await scope.runtime.host.secrets.set(named(name), value);
         },
         delete: async (name) => scope.runtime.host.secrets.delete(named(name)),

package/dist/plugin/testing.d.ts

@@ -2,7 +2,14 @@ import type { Server } from "node:net";
 import { HostError } from "../wire.ts";
 import type { PackageManifest, PackageSource } from "./types.ts";
 import type { Json, LayoutSlot, LocalServices, PlaybackStats, Transport, WireSystemInfo } from "../wire.ts";
-import { COMMAND_LIMITS, MENU_IDS } from "../commands.ts";
+import { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS } from "../commands.ts";
+import type { BuiltinCommand, BuiltinSubmenu } from "../commands.ts";
+import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.ts";
+import type { CapabilityInfo } from "../capabilities.ts";
+import { OSD_LIMITS } from "./osd.ts";
+import { SECRET_LIMITS } from "./services.ts";
+import { BINDING_INPUTS } from "./bindings.ts";
+import { THEME_PALETTES } from "../palettes.ts";
 import { UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
@@ -15,6 +22,22 @@ import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
 export { HostError };
 /** The player's command caps, which the test host enforces as well. */
 export { COMMAND_LIMITS, MENU_IDS };
+/** The submenus of the player's built-in plugins, by key path. */
+export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS };
+export type { BuiltinCommand, BuiltinSubmenu };
+/** The manifest capabilities: what each opens and how the store shows it. */
+export { CAPABILITY_INFO };
+export type { CapabilityInfo };
+/** The longest message a plugin may send the player. */
+export { MESSAGE_LIMIT };
+/** The player's limits on the on-screen display. */
+export { OSD_LIMITS };
+/** The player's limits on stored secrets. */
+export { SECRET_LIMITS };
+/** The names bindings are made of. */
+export { BINDING_INPUTS };
+/** The colours of the player's palettes, by `Theme` token. */
+export { THEME_PALETTES };
 /** The player's property value limits, which the test host enforces as well. */
 export { UI_VALUE_LIMITS };
 /**

package/dist/plugin/testing.js

@@ -65,7 +65,12 @@ import { tmpdir } from "node:os";
 import { extname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HostError } from "../wire.js";
-import { COMMAND_LIMITS, MENU_IDS } from "../commands.js";
+import { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "../commands.js";
+import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
+import { OSD_LIMITS } from "./osd.js";
+import { SECRET_LIMITS } from "./services.js";
+import { BINDING_INPUTS } from "./bindings.js";
+import { THEME_PALETTES } from "../palettes.js";
 import { UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
 import { nodeProblem } from "../processing.js";
 import { RENDER_DEFAULTS, renderProblem, VIEW_DEFAULTS, viewProblem, } from "./view.js";
@@ -76,6 +81,20 @@ import { Catalog, format as formatTemplate, HOST_GROUPS, HOST_ZH_HANS, LOCALES,
 export { HostError };
 /** The player's command caps, which the test host enforces as well. */
 export { COMMAND_LIMITS, MENU_IDS };
+/** The submenus of the player's built-in plugins, by key path. */
+export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS };
+/** The manifest capabilities: what each opens and how the store shows it. */
+export { CAPABILITY_INFO };
+/** The longest message a plugin may send the player. */
+export { MESSAGE_LIMIT };
+/** The player's limits on the on-screen display. */
+export { OSD_LIMITS };
+/** The player's limits on stored secrets. */
+export { SECRET_LIMITS };
+/** The names bindings are made of. */
+export { BINDING_INPUTS };
+/** The colours of the player's palettes, by `Theme` token. */
+export { THEME_PALETTES };
 /** The player's property value limits, which the test host enforces as well. */
 export { UI_VALUE_LIMITS };
 /**
@@ -460,6 +479,7 @@ export class TestHost {
         session: 0,
         framesShown: 0,
         framesDropped: 0,
+        presentedFps: null,
         video: null,
         audio: null,
         avSyncMs: null,
@@ -2545,8 +2565,8 @@ export class TestHost {
         },
         "osd.show": (p) => {
             const text = this.#shown(p.text, p.args, "text").replace(/[\n\r]/g, " ");
-            if (!text.trim() || [...text].length > 200)
-                throw new HostError("invalid", "osd text needs 1..200 characters");
+            if (!text.trim() || [...text].length > OSD_LIMITS.messageChars)
+                throw new HostError("invalid", `osd text needs 1..${OSD_LIMITS.messageChars} characters`);
             this.osd.push(text);
         },
         "osd.panel": (p) => {
@@ -2554,10 +2574,20 @@ export class TestHost {
                 return void (this.osdPanel = null);
             const max = p.maxColumns;
             if (max !== undefined &&
-                !(Number.isInteger(max) && Number(max) >= 8 && Number(max) <= 1000))
-                throw new HostError("invalid", "maxColumns is an integer from 8 to 1000");
-            const text = this.#shown(p.text, p.args, "text");
-            this.osdPanel = max === undefined ? text : fitColumns(text, Number(max));
+                !(Number.isInteger(max) &&
+                    Number(max) >= OSD_LIMITS.minColumns &&
+                    Number(max) <= OSD_LIMITS.maxColumns))
+                throw new HostError("invalid", `maxColumns is an integer from ${OSD_LIMITS.minColumns} to ${OSD_LIMITS.maxColumns}`);
+            const shown = this.#shown(p.text, p.args, "text");
+            const text = max === undefined ? shown : fitColumns(shown, Number(max));
+            // As the player: \n separates lines, a trailing one ends the last.
+            const lines = text.split("\n");
+            if (text.endsWith("\n"))
+                lines.pop();
+            if (Buffer.byteLength(text) > OSD_LIMITS.panelBytes ||
+                lines.length > OSD_LIMITS.panelLines)
+                throw new HostError("invalid", `osd panel allows ${OSD_LIMITS.panelLines} lines, ${OSD_LIMITS.panelBytes} bytes`);
+            this.osdPanel = text;
         },
         "playback.stats": () => this.stats,
         "audio.addTrack": (p) => {