@vestra-player/sdk 1.6.3 → 1.6.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.6.4
+
+**Who must change: nobody, but check tests that compare whole `bindings.list()` entries.** Additions only: two optional `CommandOptions` fields, one optional `BindingInfo` field, a `COMMAND_LIMITS` entry and a new built-in command. `apiVersion` stays `vestra/1`, no new capability. A plugin that does not set the new fields sends exactly what it sent before; one that sets them needs player 0.7.6 (`"minPlayerVersion": "0.7.6"`), because older players refuse a declaration with fields they do not know (`invalid`).
+
+- **`CommandOptions.category`** (player 0.7.6): what a command is about, in a word or two (`"Subtitle Sync"`), English source text translated like the title, or a `Text`. The player's new command palette (Ctrl+Shift+P, ⌘⇧P on macOS) and lists of commands name a command `Category: Title`, so a title such as "Earlier 0.5 s" or "Off" still says what it changes outside its menu. Without one the player uses the menu path above the item, then the plugin's name. 1–80 bytes (`COMMAND_LIMITS.categoryBytes`), checked like the other command texts. See [The command palette and categories](docs/explanation/commands.md#the-command-palette-and-categories).
+- **`CommandOptions.home`** (player 0.7.6): the local id of the plugin's command that opens the window or panel where this command's control lives; the palette shows that place. Checked like a command id.
+- **`BindingInfo.category`** (player 0.7.6): the shown category from `bindings.list`, `null` without one, for a keyboard shortcuts page that names commands like the palette.
+- **`BUILTIN_COMMANDS`** lists the player's **Command Palette** (`host/palette`, `Ctrl+Shift+P`, outside the menu). From player 0.7.6 a plugin that declares `Ctrl+Shift+P` as a default key loses it to this command (the player's own commands win conflicts); no built-in plugin declares it.
+- **`bindings.list()` entries now carry `category`** (`null` when the command declares none), in the player and in `TestHost`. A test that compares a whole entry with `deepEqual` now needs `category` in the expected value.
+- **The palette lists a disabled command only when it gives a `reason`.** A command that is disabled without one is left out, whatever its keys (as VS Code hides a command whose `when` is false), so give a `reason` to a command that should stay findable while it is disabled.
+- `TestHost` checks `category` and `home` as the player does, shows the translated category in `FakeCommand.display.category` (not enumerable, like `reason`) and in its `bindings.list` entries.
+
 ## 1.6.3
 
 **Who must change: nobody.** Documentation only: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability, no player version needed.

package/dist/commands.d.ts

@@ -78,6 +78,13 @@ export declare const COMMAND_LIMITS: {
      * @since 1.5.48
      */
     readonly groupBytes: 80;
+    /**
+     * UTF-8 bytes of a category (`CommandOptions.category`), a text value
+     * counted by its English rendering.
+     *
+     * @since 1.6.4
+     */
+    readonly categoryBytes: 80;
     /**
      * UTF-8 bytes of a state's reason, as shown in the player's
      * language.
@@ -327,6 +334,16 @@ export type CommandDeclaration = {
         icon: string | Json;
         order: number;
     };
+    /**
+     * The command's category, source text or a text value (player 0.7.6).
+     * Sent only when set: older players refuse unknown declaration fields.
+     */
+    category?: string | TextJson;
+    /**
+     * The local id of the command that opens where this one lives (player
+     * 0.7.6). Sent only when set, like `category`.
+     */
+    home?: string;
 };
 export declare function commandClient(transport: Transport): {
     register: (id: string, revision: number, declaration: CommandDeclaration, state: CommandState, when?: CommandWhen) => Promise<{

package/dist/commands.js

@@ -74,6 +74,13 @@ export const COMMAND_LIMITS = {
      * @since 1.5.48
      */
     groupBytes: 80,
+    /**
+     * UTF-8 bytes of a category (`CommandOptions.category`), a text value
+     * counted by its English rendering.
+     *
+     * @since 1.6.4
+     */
+    categoryBytes: 80,
     /**
      * UTF-8 bytes of a state's reason, as shown in the player's
      * language.
@@ -594,6 +601,7 @@ host | quit | Quit | Cmd+Q
 host | enter-fullscreen | (Enter Fullscreen)
 host | exit-fullscreen | (Leave Fullscreen)
 host | sidebar | (Toggle Sidebar)
+host | palette | (Command Palette) | Ctrl+Shift+P
 vestra.info | info.brief | (Brief Info) | Shift+Tab
 vestra.playlist | playlist.play | (Play) | Enter, P | panel
 vestra.playlist | playlist.list-add | (Add Files…) | Ctrl+I | panel

package/dist/plugin/bindings.js

@@ -189,6 +189,7 @@ export const bindingsApi = (scope) => ({
                 title: info.title,
                 path: info.path,
                 key: info.key ?? null,
+                category: info.category ?? null,
                 scope: info.scope,
                 defaults: info.defaults,
                 current: info.current,

package/dist/plugin/commands.js

@@ -26,13 +26,18 @@ function declare(options) {
         throw failure("invalid", `command ${options.id}: title or path required`);
     if (path.length > 8)
         throw failure("invalid", `command ${options.id}: path has 1–8 segments`);
-    for (const segment of [title, ...path])
+    const category = options.category;
+    for (const segment of [
+        title,
+        ...path,
+        ...(category === undefined ? [] : [category]),
+    ])
         if (typeof segment !== "string") {
             const problem = isTextValue(segment)
                 ? "$vestraList" in segment
                     ? "a menu text is a string or a text, not a list"
                     : textProblem(segment)
-                : "title and path segments are strings or texts";
+                : "title, path segments and category are strings or texts";
             if (problem)
                 throw failure("invalid", `command ${options.id}: ${problem}`);
         }
@@ -59,6 +64,14 @@ function declare(options) {
     // 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);
+    // Only when set: players before 0.7.6 refuse the fields.
+    if (category !== undefined)
+        declaration.category = category;
+    if (options.home !== undefined) {
+        if (typeof options.home !== "string")
+            throw failure("invalid", `command ${options.id}: home is a command id`);
+        declaration.home = options.home;
+    }
     return declaration;
 }
 /** `CommandOptions.button`, checked as the player checks it, in wire form. */

package/dist/plugin/testing.d.ts

@@ -270,6 +270,14 @@ export interface FakeCommand {
          * @since 1.5.11
          */
         reason?: string | null;
+        /**
+         * The category as shown (`CommandOptions.category`, translated with
+         * the plugin's catalog), `null` without one. Not enumerable, like
+         * `reason`.
+         *
+         * @since 1.6.4
+         */
+        category?: string | null;
     };
     /**
      * The conditions the plugin sent for `enabled` and `checked`

package/dist/plugin/testing.js

@@ -354,7 +354,7 @@ function menuTextKey(value) {
  * The declaration checks of the player's `Registry::register`, in its
  * order, on the keyed title and path (`@<id>` already replaced).
  */
-function checkDeclaration(id, title, path, declaration) {
+function checkDeclaration(id, title, path, declaration, category = null) {
     commandText(id, "localId", COMMAND_LIMITS.idBytes);
     if (!/^[A-Za-z0-9._-]+$/.test(id))
         throw commandInvalid("localId permits ASCII letters, digits, '.', '_' and '-'");
@@ -367,6 +367,17 @@ function checkDeclaration(id, title, path, declaration) {
     if (typeof group !== "string")
         throw new HostError("invalid", "group is a string");
     commandText(group, "group", COMMAND_LIMITS.groupBytes);
+    // Player 0.7.6: the category and the home command's local id.
+    if (category !== null)
+        commandText(category, "category", COMMAND_LIMITS.categoryBytes);
+    const home = declaration.home;
+    if (home !== undefined && home !== null) {
+        if (typeof home !== "string")
+            throw new HostError("invalid", "home is a command id");
+        commandText(home, "home", COMMAND_LIMITS.idBytes);
+        if (!/^[A-Za-z0-9._-]+$/.test(home))
+            throw commandInvalid("home permits ASCII letters, digits, '.', '_' and '-'");
+    }
     const order = declaration.order ?? 0;
     if (!Number.isInteger(order) ||
         Math.abs(order) > COMMAND_LIMITS.order)
@@ -669,7 +680,7 @@ export class TestHost {
             : formatTemplate(shown, args);
     }
     /** A declared menu path and title as the player shows them. */
-    #display(path, title, reason = null) {
+    #display(path, title, reason = null, category = null) {
         const keys = menuKeys(path.map((segment) => typeof segment === "string" ? segment : textKey(segment)));
         const display = {
             title: this.translate(title),
@@ -684,6 +695,10 @@ export class TestHost {
             value: reason === null ? null : this.translate(reason),
             enumerable: false,
         });
+        Object.defineProperty(display, "category", {
+            value: category === null ? null : this.translate(category),
+            enumerable: false,
+        });
         return display;
     }
     /**
@@ -3230,6 +3245,8 @@ export class TestHost {
                 key: declaration.path?.length
                     ? menuKeys(declaration.path.map((segment) => typeof segment === "string" ? segment : textKey(segment)))
                     : null,
+                // Player 0.7.6: the category as shown, `null` without one.
+                category: shown?.display.category ?? null,
                 scope: scope,
                 defaults: declaration.bindings,
                 current,
@@ -4086,7 +4103,11 @@ export class TestHost {
             if (menu !== null && keys.length < 2)
                 throw commandInvalid(`menu id @${menu} needs an item after it`);
             const path = menuKeys(keys);
-            checkDeclaration(id, title, path, declaration);
+            // Player 0.7.6: the category, keyed like a menu text.
+            const category = declaration.category === undefined || declaration.category === null
+                ? null
+                : menuTextKey(declaration.category);
+            checkDeclaration(id, title, path, declaration, category);
             if (button !== undefined && button !== null) {
                 if (path.length === 0)
                     throw commandInvalid("button needs a menu path: a bar button is also a menu item");
@@ -4144,7 +4165,7 @@ export class TestHost {
             this.commands.set(id, {
                 declaration,
                 get display() {
-                    return host.#display(declaration.path ?? [], declaration.title, this.state.reason);
+                    return host.#display(declaration.path ?? [], declaration.title, this.state.reason, declaration.category ?? null);
                 },
                 ...(p.when ? { when: p.when } : {}),
                 get state() {

package/dist/plugin/types.d.ts

@@ -1112,6 +1112,87 @@ export interface CommandOptions {
      * defaults to the last path segment.
      */
     title?: string | Text;
+    /**
+     * What the command is about, in a word or two (`"Subtitle Sync"`,
+     * `"Picture"`): English source text, shown translated like `title`, or a
+     * {@link Text}. The player's command palette (Ctrl+Shift+P, ⌘⇧P on macOS)
+     * and lists of commands name a command `Category: Title`, so a short title
+     * such as "Earlier 0.5 s", "Off" or "90°" still says what it changes once
+     * it is out of the menu. Without it the player uses the menu path above
+     * the item, then the plugin's name.
+     *
+     * 1–80 UTF-8 bytes (a text value counted by its English rendering), no
+     * control characters, no whitespace at either end
+     * (`COMMAND_LIMITS.categoryBytes`); the player refuses anything else with
+     * `invalid`. Sent only when set: players before 0.7.6 refuse the field
+     * with `invalid`, so declare `"minPlayerVersion": "0.7.6"` when you set
+     * it.
+     *
+     * @example Name commands that have no menu path
+     * The palette lists "Subtitle Sync: Earlier 0.5 s" and "Subtitle Sync:
+     * Later 0.5 s"; without a category both would read as a bare "Earlier
+     * 0.5 s", indistinguishable from an audio delay command of the same name.
+     * ```ts
+     * declare function shift(seconds: number): void;
+     * // ---cut---
+     * for (const [id, title, seconds] of [
+     *   ["sync-earlier", "Earlier 0.5 s", -0.5],
+     *   ["sync-later", "Later 0.5 s", 0.5],
+     * ] as const)
+     *   plugin.commands.add({
+     *     id,
+     *     title,
+     *     category: "Subtitle Sync", // the palette reads "Subtitle Sync: Earlier 0.5 s"
+     *     bindings: [id === "sync-earlier" ? "." : ","],
+     *     run: () => shift(seconds),
+     *   });
+     * ```
+     *
+     * @player 0.7.6 (declare `"minPlayerVersion": "0.7.6"`; older players
+     * refuse the declaration with `invalid`).
+     * @since 1.6.4
+     */
+    category?: string | Text;
+    /**
+     * The id of this plugin's command that opens the window or panel where
+     * this command's control lives (`"tune"` for a Subtitle Tuning… command
+     * whose window has the sync slider). The player's command palette shows
+     * that place next to the command. A local id, like `id`: ASCII letters,
+     * digits, `.`, `_` and `-`, 1–128 bytes; the player refuses anything else
+     * with `invalid`. The command it names need not be registered yet; while
+     * it is not, the palette shows the place it would show without `home`:
+     * the menu path above the item, "Menu" for a top-level item, nothing for
+     * a command outside the menu. Sent only when set: players
+     * before 0.7.6 refuse the field with `invalid`, so declare
+     * `"minPlayerVersion": "0.7.6"` when you set it.
+     *
+     * @example Point a key command at its window
+     * The palette row for "Subtitle Sync: Earlier 0.5 s" also says where the
+     * same setting can be changed by hand: the Subtitle Tuning window that the
+     * `tune` command opens.
+     * ```ts
+     * declare const tuning: { show(): void };
+     * declare function shift(seconds: number): void;
+     * // ---cut---
+     * plugin.commands.add({
+     *   id: "tune",
+     *   path: ["@subtitles", "Subtitle Tuning…"],
+     *   run: () => tuning.show(),
+     * });
+     * plugin.commands.add({
+     *   id: "sync-earlier",
+     *   title: "Earlier 0.5 s",
+     *   category: "Subtitle Sync",
+     *   home: "tune", // the palette shows "Subtitle Tuning" as its place
+     *   run: () => shift(-0.5),
+     * });
+     * ```
+     *
+     * @player 0.7.6 (declare `"minPlayerVersion": "0.7.6"`; older players
+     * refuse the declaration with `invalid`).
+     * @since 1.6.4
+     */
+    home?: string;
     /**
      * Sibling order in the menu, ascending (integer, default 0). A submenu sits
      * where its first command sits, except a built-in menu, which keeps its
@@ -9201,6 +9282,16 @@ export interface BindingInfo extends BindingRef {
      * @since 1.5.11
      */
     key?: string[] | null;
+    /**
+     * The command's category as shown ({@link CommandOptions.category},
+     * translated), `null` when it declares none (and always from players
+     * before 0.7.6). Always set by `list()`; optional so that test fakes
+     * written for older SDKs still type-check. A list of commands names one `Category: Title`; without a
+     * category, use the menu path (`path`) as before.
+     *
+     * @since 1.6.4
+     */
+    category?: string | null;
     /** Global, or only while the plugin's panel has focus. */
     scope: "global" | "panel";
     /** The command's own bindings. */

package/dist/wire.d.ts

@@ -209,6 +209,8 @@ export interface BindingTable {
         path: string[] | null;
         /** The path's keys (player 0.4.3). */
         key?: string[] | null;
+        /** The shown category (player 0.7.6). */
+        category?: string | null;
         scope: "global" | "panel";
         defaults: string[];
         current: string[];

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.6.3: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
+> @vestra-player/sdk 1.6.4: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
 
 ## Read the documentation
 

package/package.json

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