@vestra-player/sdk 1.5.12 → 1.5.14

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.5.14
+
+**The documentation site in seven groups, with generated reference tables.** A documentation release; `apiVersion` stays `vestra/1`, and plugins need no change. Everything a plugin author needs is now on the [documentation site](https://vestrasys.github.io/vestra-player-sdk/) once, in English.
+
+- **Seven groups**: Tutorials, Concepts, How-to, Guidelines, Examples, Reference and API. `scripts/doc-structure.mjs` lists every page and why it is a page of its own; `npm run docs:check` fails on a page that is not listed, a page without a `description`, a placeholder ("coming soon"), a nested folder, a stale generated table or a page far over its size limit.
+- **Reference** (new): Manifest (every field and the player version each newer part of the API needs), Capabilities, Limits, Commands, menus and bindings (built-in menus, submenu keys in use, the built-in commands and their default keys, binding syntax and names, core actions, the keys the system takes first), Platforms, Theme (tokens with their current `vestra` values, fonts, icons, widgets) and Command line. Their tables are generated from the SDK's code and Slint files (`npm run docs:tables`), so they cannot drift from it.
+- **Guidelines** (new): interface and menu rules.
+- **New pages**: Concepts *How a plugin runs*, *Commands, menus and key bindings*, *Playback state, controls and sources*, *Video and audio processing*; How-to *Test a plugin*, *Publish a plugin*; *Translate a plugin* gains the language list and the machine translation review. Getting started and the README link to the Reference instead of repeating its tables; the old compatibility tables are replaced by the generated player version table.
+- **New exports** for the generated tables and for tests (`@vestra-player/sdk/testing`): `CAPABILITY_INFO` (per capability: the members it opens, the capabilities they also need, the store's wording, whether the store highlights it; `CAPABILITIES` is derived from it), `MESSAGE_LIMIT` (1 MiB per message), `OSD_LIMITS`, `SECRET_LIMITS`, `BINDING_INPUTS` (the key and mouse names a binding is made of), `BUILTIN_SUBMENUS` (the submenu keys the built-in plugins use), `BUILTIN_COMMANDS` (the built-in commands with their menu paths and default keys) and `THEME_PALETTES` (the colours of `vestra` and `vestra-light` by `Theme` token). The player's tests check them against the player.
+- **`TestHost`** enforces the information block's limits like the player: `OsdPanel.set` with more than 32 lines or 4096 bytes (after `maxColumns` is applied) fails with `invalid`.
+- `llms.txt` lists every capability and points at every page of the site in `llms-full.txt`, which now contains all of them.
+
+## 1.5.13
+
+**`i18n extract` keeps the translator's comments and writes the right number of plural forms.** A fix; `apiVersion` stays `vestra/1`.
+
+- Merging into a `locales/<lang>.po` kept only the header's text: comment lines before the header (`# Reviewed by an AI reviewer on 2026-10-25`, `# Translator: …`, `#, fuzzy`) and the translator's own `# ` comments on entries were dropped. Both are now kept as written (`parsePo` returns `headerComments`, entries carry `comments`; `writePo` writes them).
+- A plural entry has exactly `nplurals` `msgstr[n]` lines, from the file's `Plural-Forms` (or the language: one for `ja`, `ko`, `zh-Hans`). Before, every plural entry got an empty `msgstr[1]`, also in one-form languages; a merge now removes such an extra empty line (a filled one stays).
+
 ## 1.5.12
 
 **Keys of disabled commands pass on; `i18n check` fails on stale catalogs; translator notes in tables; the Button follows its text.** A fix release; `apiVersion` stays `vestra/1`.

package/README.md

@@ -72,31 +72,23 @@ Complete, tested plugins in [`examples/`](https://github.com/vestrasys/vestra-pl
 | [menus](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/menus)                       | Radio items, separator groups and a menu item whose title changes.       | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Menus.html)            |
 | [theme-widgets](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/theme-widgets)       | A tool window drawn with the player's theme and widgets.                 | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Theme_widgets.html)    |
 | [markdown](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/markdown)                 | A window that shows a Markdown document.                                 | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Markdown.html)         |
-| [i18n](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/i18n)                         | A plugin in the player's language: English source text, a translation.  | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Counter__i18n_.html)            |
+| [i18n](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/i18n)                         | A plugin in the player's language: English source text, a translation.  | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Counter_%28i18n%29.html)            |
 
-## Command line
+## Documentation
 
-| Command                                                     | Does                                                                       |
-| ----------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `vestra-plugin check [dir...]`                              | Checks the manifest, then a strict type check of the plugin and its tests. |
-| `vestra-plugin test [dir...]`                               | Runs `node --test` on `tests/*.test.{ts,mjs}`.                             |
-| `vestra-plugin build [dir...] [--version x.y.z]`            | Writes `dist/`: types stripped, files copied, manifest versioned.          |
-| `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]` | Builds, then packs `dist/` as `<id>-<version>.vxp`.                        |
-| `vestra-plugin i18n extract [dir...] [--locale lang]`       | Collects the texts to translate into `locales/`, keeping translations.     |
-| `vestra-plugin i18n check [dir...]`                         | Translation coverage and untranslatable text; fails on stale catalogs.     |
+The [documentation site](https://vestrasys.github.io/vestra-player-sdk/) is the one place for everything a plugin author needs:
 
-## Compatibility
+- **[Tutorials](https://vestrasys.github.io/vestra-player-sdk/documents/Tutorials.html)**: [Getting started](https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html), from an empty folder to a packed plugin.
+- **[Concepts](https://vestrasys.github.io/vestra-player-sdk/documents/Concepts.html)**: how a plugin runs, commands and key bindings, playback, video and audio processing, the interface.
+- **[How-to guides](https://vestrasys.github.io/vestra-player-sdk/documents/How-to_guides.html)**: testing, translating and publishing a plugin, responsive sliders, remembering window state.
+- **[Guidelines](https://vestrasys.github.io/vestra-player-sdk/documents/Guidelines.html)**: rules for the interface and the menus.
+- **[Examples](https://vestrasys.github.io/vestra-player-sdk/documents/Examples.html)**: the walkthroughs above.
+- **[Reference](https://vestrasys.github.io/vestra-player-sdk/documents/Reference.html)**: capabilities, manifest fields, limits, menus and bindings, platforms, theme, and the [command line](https://vestrasys.github.io/vestra-player-sdk/documents/Command_line.html) (`vestra-plugin check`, `test`, `build`, `pack`, `i18n extract`, `i18n check`).
+- **[API](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html)**: every type and member of `@vestra-player/sdk` and `@vestra-player/sdk/testing`.
 
-| SDK | Plugin API | Vestra Player                                                                             | Node.js                      |
-| --- | ---------- | ----------------------------------------------------------------------------------------- | ---------------------------- |
-| 1.0 | `vestra/1` | 0.1 or newer                                                                              | 22.18 or newer               |
-| 1.1 | `vestra/1` | 0.2 or newer for the 1.1 additions                                                        | 22.18 or newer               |
-| 1.2 | `vestra/1` | 0.2 or newer                                                                              | 26 (shipped with the player) |
-| 1.3 | `vestra/1` | 0.2 or newer; 0.3 for the 1.3 additions (menu ids, `Theme.danger`, empty video chains)    | 26 (shipped with the player) |
-| 1.4 | `vestra/1` | 0.2 or newer; 0.3 for the 1.3 additions. `ThemeId` is `"vestra"` only (see the CHANGELOG) | 26 (shipped with the player) |
-| 1.5 | `vestra/1` | 0.2 or newer; 0.3 for the 1.3 additions; 0.4 for the 1.5 additions (`vestra-light`, `@vestra/icons.slint`); 0.4.3 for translations (1.5.9) | 26 (shipped with the player) |
+## Compatibility
 
-Minor releases only add backwards-compatible API; a breaking change gets a new `apiVersion` and a new major version. `@vestra-player/sdk/runtime` is for the player only and not covered by semver.
+Every 1.x release implements the plugin API `vestra/1`: minor releases only add backwards-compatible API, and a breaking change gets a new `apiVersion` and a new major version. Plugins run on the Node.js 26 that the player ships. API added after SDK 1.0 may need a newer player; [Player versions](https://vestrasys.github.io/vestra-player-sdk/documents/Manifest.html#player-versions) lists which API needs which player, for the manifest's `minPlayerVersion`. `@vestra-player/sdk/runtime` is for the player only and not covered by semver.
 
 ## Contributing · License
 

package/dist/capabilities.d.ts

@@ -1,7 +1,79 @@
 /**
- * Manifest capabilities the player knows (`vestra/1`). The same list as the
+ * What one manifest capability is for: the members it opens, the
+ * capabilities they also need, and how the plugin store describes it. An
+ * entry of {@link CAPABILITY_INFO}.
+ *
+ * @since 1.5.14
+ */
+export interface CapabilityInfo {
+    /**
+     * The members this capability opens, as `Interface.member` (for example
+     * `Commands.add` is `plugin.commands.add`). A call to one of them without
+     * the capability fails with code `capability`; `Plugin.video.filter` is
+     * `plugin.video.filter`. A member can be listed
+     * under more than one capability when it needs all of them
+     * (`Panel.onChange` needs `ui.mount` and `events`).
+     */
+    readonly apis: readonly string[];
+    /**
+     * Capabilities every member in {@link CapabilityInfo.apis} also needs:
+     * declare them as well. What only one member or one option needs
+     * (`Plugin.video.filter` also needs `events`) is documented at that member.
+     */
+    readonly requires: readonly string[];
+    /**
+     * How the plugin store and the player's install confirmation describe the
+     * capability to the user, in English (the player translates it). Two
+     * capabilities can share one description (`media.read` and
+     * `media.control`); the store then shows it once.
+     */
+    readonly label: string;
+    /**
+     * `true` when the store highlights the capability as one to think about
+     * before installing (it reaches outside the plugin's own features: the
+     * clipboard, every shortcut, the keychain, other plugins).
+     */
+    readonly risky: boolean;
+}
+/**
+ * Every manifest capability the player knows (`vestra/1`), in the player's
+ * order, with the members it opens, the capabilities they also need and the
+ * store's wording. The player's tests check that the names agree with the
+ * player's `host/src/plugins.rs` and the labels with its plugin store.
+ *
+ * A member not listed under any capability needs none (`plugin.tools`,
+ * `plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui`,
+ * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
+ * and `plugin.packages.list`).
+ *
+ * @example
+ * ```ts
+ * import { CAPABILITY_INFO } from "@vestra-player/sdk/testing";
+ *
+ * const manifest = JSON.parse(await readFile("manifest.json", "utf8"));
+ * for (const capability of manifest.capabilities)
+ *   for (const needed of CAPABILITY_INFO[capability].requires)
+ *     assert.ok(manifest.capabilities.includes(needed), needed);
+ * ```
+ *
+ * @since 1.5.14
+ */
+export declare const CAPABILITY_INFO: Readonly<Record<string, CapabilityInfo>>;
+/**
+ * Manifest capabilities the player knows (`vestra/1`): the keys of
+ * {@link CAPABILITY_INFO}, in the player's order. The same list as the
  * player's `host/src/plugins.rs`; the player's tests check that they agree.
  */
 export declare const CAPABILITIES: readonly string[];
 /** The plugin API version this SDK implements (`manifest.apiVersion`). */
 export declare const API_VERSION = "vestra/1";
+/**
+ * The longest message a plugin may send the player, in UTF-8 bytes of one
+ * protocol line with its newline (1 MiB). The player stops a plugin that
+ * writes a longer one, so the plugin's side refuses such a request before
+ * sending it: it rejects with code `limit`. Property values meet
+ * {@link UI_VALUE_LIMITS} before this.
+ *
+ * @since 1.5.14
+ */
+export declare const MESSAGE_LIMIT: number;

package/dist/capabilities.js

@@ -1,33 +1,268 @@
 /**
- * Manifest capabilities the player knows (`vestra/1`). The same list as the
+ * Every manifest capability the player knows (`vestra/1`), in the player's
+ * order, with the members it opens, the capabilities they also need and the
+ * store's wording. The player's tests check that the names agree with the
+ * player's `host/src/plugins.rs` and the labels with its plugin store.
+ *
+ * A member not listed under any capability needs none (`plugin.tools`,
+ * `plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui`,
+ * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
+ * and `plugin.packages.list`).
+ *
+ * @example
+ * ```ts
+ * import { CAPABILITY_INFO } from "@vestra-player/sdk/testing";
+ *
+ * const manifest = JSON.parse(await readFile("manifest.json", "utf8"));
+ * for (const capability of manifest.capabilities)
+ *   for (const needed of CAPABILITY_INFO[capability].requires)
+ *     assert.ok(manifest.capabilities.includes(needed), needed);
+ * ```
+ *
+ * @since 1.5.14
+ */
+export const CAPABILITY_INFO = Object.freeze({
+    "producer.av": {
+        apis: ["Player.openStream"],
+        requires: ["playback.control"],
+        label: "Provide audio and video it generates itself",
+        risky: false,
+    },
+    "playback.read": {
+        apis: [
+            "Player.state",
+            "Player.refresh",
+            "Player.stats",
+            "Player.chapters",
+            "Player.audioDevices",
+            "Timeline.marks",
+        ],
+        requires: [],
+        label: "Read what is playing and the position",
+        risky: false,
+    },
+    "playback.control": {
+        apis: [
+            "Player.open",
+            "Player.setPaused",
+            "Player.seek",
+            "Player.setRate",
+            "Player.restart",
+            "Player.close",
+            "Player.scrub",
+            "Player.setOutput",
+            "Player.provideSequence",
+            "Player.next",
+            "Player.previous",
+            "Player.addAudioTrack",
+            "Player.selectAudioTrack",
+            "Player.step",
+            "Player.setStepSeek",
+            "Player.setLoop",
+            "Player.setAudioDevice",
+            "Power.preventSleep",
+        ],
+        requires: [],
+        label: "Open media, control playback, keep the computer awake",
+        risky: false,
+    },
+    "source.resolve": {
+        apis: ["Resolvers.add"],
+        requires: [],
+        label: "Resolve online video addresses",
+        risky: false,
+    },
+    events: {
+        apis: [
+            "Player.onChange",
+            "Subtitles.onChange",
+            "Timeline.onChange",
+            "MainWindow.onChange",
+            "Appearance.onChange",
+            "PanelSlot.onChange",
+            "Panel.onChange",
+            "BackdropSlot.onChange",
+            "Resolvers.onFileTypesChange",
+        ],
+        requires: [],
+        label: "Receive playback changes as they happen",
+        risky: false,
+    },
+    commands: {
+        apis: ["Commands.add", "Host.run"],
+        requires: [],
+        label: "Add menu commands and shortcuts",
+        risky: false,
+    },
+    "ui.window": {
+        apis: ["Windows.create"],
+        requires: [],
+        label: "Open tool windows",
+        risky: false,
+    },
+    "ui.mount": {
+        apis: [
+            "Panels.mount",
+            "Panels.bottom",
+            "Panels.sidebar",
+            "Panels.backdrop",
+            "PanelSlot.onChange",
+            "Panel.onChange",
+            "BackdropSlot.onChange",
+        ],
+        requires: [],
+        label: "Show panels in the bottom bar, the sidebar or behind the video",
+        risky: false,
+    },
+    "ui.dialog": {
+        apis: [
+            "Dialogs.confirm",
+            "Dialogs.openFile",
+            "Dialogs.openFiles",
+            "Dialogs.openDirectory",
+            "Dialogs.saveFile",
+        ],
+        requires: [],
+        label: "Show file pickers and confirmations",
+        risky: false,
+    },
+    "plugins.manage": {
+        apis: [
+            "Packages.validate",
+            "Packages.validateArchive",
+            "Packages.rollback",
+            "Packages.setEnabled",
+            "Packages.uninstall",
+        ],
+        requires: [],
+        label: "Install, uninstall and disable other plugins",
+        risky: true,
+    },
+    "processing.video": {
+        apis: ["Plugin.video.filter", "Plugin.video.view", "Plugin.video.render"],
+        requires: ["playback.read"],
+        label: "Process the picture (filters, shaders)",
+        risky: false,
+    },
+    "processing.audio": {
+        apis: ["Plugin.audio.filter"],
+        requires: ["playback.read", "events"],
+        label: "Process the sound",
+        risky: false,
+    },
+    "subtitles.read": {
+        apis: ["Subtitles.state", "Subtitles.onChange", "Subtitles.refresh"],
+        requires: [],
+        label: "Read subtitles",
+        risky: false,
+    },
+    "subtitles.control": {
+        apis: [
+            "Subtitles.select",
+            "Subtitles.load",
+            "Subtitles.remove",
+            "Subtitles.setStyle",
+        ],
+        requires: [],
+        label: "Load and change subtitles",
+        risky: false,
+    },
+    "media.read": {
+        apis: ["MediaCapture.capture", "Snapshot.export"],
+        requires: ["media.control"],
+        label: "Take snapshots and export clips",
+        risky: false,
+    },
+    "media.control": {
+        apis: ["MediaCapture.capture", "Snapshot.export"],
+        requires: ["media.read"],
+        label: "Take snapshots and export clips",
+        risky: false,
+    },
+    "ui.osd": {
+        apis: ["Osd.show", "Osd.panel"],
+        requires: [],
+        label: "Show messages on the video",
+        risky: false,
+    },
+    clipboard: {
+        apis: [
+            "Clipboard.readText",
+            "Clipboard.writeText",
+            "Clipboard.writeImage",
+        ],
+        requires: [],
+        label: "Read and write the clipboard",
+        risky: true,
+    },
+    "window.control": {
+        apis: [
+            "MainWindow.setVideoArea",
+            "MainWindow.setAlwaysOnTop",
+            "MainWindow.setCursorAutoHide",
+            "MainWindow.setPictureInPicture",
+        ],
+        requires: [],
+        label: "Adjust the main window (size, on top, picture-in-picture)",
+        risky: false,
+    },
+    "bindings.manage": {
+        apis: [
+            "Bindings.list",
+            "Bindings.set",
+            "Bindings.reset",
+            "Bindings.onChange",
+        ],
+        requires: [],
+        label: "Change all shortcuts",
+        risky: true,
+    },
+    "timeline.marks": {
+        apis: ["Timeline.layer"],
+        requires: [],
+        label: "Show marks on the progress bar",
+        risky: false,
+    },
+    "ui.drop": {
+        apis: ["Drops.provide", "Panel.onDrop"],
+        requires: [],
+        label: "Receive files dropped on the player",
+        risky: false,
+    },
+    "ui.settings": {
+        apis: ["Settings.page", "Settings.show"],
+        requires: [],
+        label: "Add pages to the Options window",
+        risky: false,
+    },
+    "ui.theme": {
+        apis: ["Appearance.set", "Appearance.setLanguage"],
+        requires: [],
+        label: "Change the player's palette",
+        risky: false,
+    },
+    secrets: {
+        apis: ["Secrets.get", "Secrets.set", "Secrets.delete"],
+        requires: [],
+        label: "Store sign-in details in the system keychain",
+        risky: true,
+    },
+});
+/**
+ * Manifest capabilities the player knows (`vestra/1`): the keys of
+ * {@link CAPABILITY_INFO}, in the player's order. The same list as the
  * player's `host/src/plugins.rs`; the player's tests check that they agree.
  */
-export const CAPABILITIES = [
-    "producer.av",
-    "playback.read",
-    "playback.control",
-    "source.resolve",
-    "events",
-    "commands",
-    "ui.window",
-    "ui.mount",
-    "ui.dialog",
-    "plugins.manage",
-    "processing.video",
-    "processing.audio",
-    "subtitles.read",
-    "subtitles.control",
-    "media.read",
-    "media.control",
-    "ui.osd",
-    "clipboard",
-    "window.control",
-    "bindings.manage",
-    "timeline.marks",
-    "ui.drop",
-    "ui.settings",
-    "ui.theme",
-    "secrets",
-];
+export const CAPABILITIES = Object.freeze(Object.keys(CAPABILITY_INFO));
 /** The plugin API version this SDK implements (`manifest.apiVersion`). */
 export const API_VERSION = "vestra/1";
+/**
+ * The longest message a plugin may send the player, in UTF-8 bytes of one
+ * protocol line with its newline (1 MiB). The player stops a plugin that
+ * writes a longer one, so the plugin's side refuses such a request before
+ * sending it: it rejects with code `limit`. Property values meet
+ * {@link UI_VALUE_LIMITS} before this.
+ *
+ * @since 1.5.14
+ */
+export const MESSAGE_LIMIT = 1024 * 1024;

package/dist/commands.d.ts

@@ -44,6 +44,95 @@ export declare const COMMAND_LIMITS: {
  * ```
  */
 export declare const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings"];
+/**
+ * A submenu that one of the player's built-in plugins declares: an entry of
+ * {@link BUILTIN_SUBMENUS}.
+ *
+ * @since 1.5.14
+ */
+export interface BuiltinSubmenu {
+    /**
+     * The submenu's key path: the English texts paths merge by, the
+     * built-in menu first by its key (`"Playback"` for `@playback`). Write
+     * these segments, followed by your command's title, to put a command into
+     * this submenu.
+     */
+    readonly path: readonly string[];
+    /** The built-in plugins that declare it (`vestra.history`). */
+    readonly plugins: readonly string[];
+}
+/**
+ * The submenus the player's built-in plugins declare, by key path, in menu
+ * order (built-in menus as in {@link MENU_IDS}, then top-level submenus).
+ * Menu paths merge by their English key, so a command whose path starts
+ * with the same keys appears in the same submenu, whatever the interface
+ * language; the submenu's title is the declaring plugin's translation. The
+ * player's own submenus (`Playback ▸ Speed`, `Playback ▸ Seek`) are not
+ * listed. The player's tests check that this list agrees with what its
+ * built-in plugins declare.
+ *
+ * @example
+ * ```ts
+ * import { BUILTIN_SUBMENUS } from "@vestra-player/sdk/testing";
+ *
+ * const snapshot = BUILTIN_SUBMENUS.find((menu) => menu.path.at(-1) === "Snapshot")!;
+ * plugin.commands.add({
+ *   id: "snapshot-to-clipboard",
+ *   path: ["@video", ...snapshot.path.slice(1), "Copy Snapshot"],
+ *   run: copySnapshot,
+ * });
+ * ```
+ *
+ * @since 1.5.14
+ */
+export declare const BUILTIN_SUBMENUS: readonly BuiltinSubmenu[];
+/**
+ * A command the player or one of its built-in plugins registers: an entry
+ * of {@link BUILTIN_COMMANDS}.
+ *
+ * @since 1.5.14
+ */
+export interface BuiltinCommand {
+    /** `"host"` for the player's own commands, else the built-in plugin's id. */
+    readonly owner: string;
+    /** The command's id within its owner (`"play-pause"`, `"capture.save"`). */
+    readonly id: string;
+    /**
+     * The menu path by key (the English texts paths merge by), the leaf
+     * included; a built-in menu by its key (`"Video"`, not `"@video"`).
+     * Empty for a command that is not in the main menu (a panel shortcut).
+     */
+    readonly path: readonly string[];
+    /** The English title (the last segment of `path` when there is one). */
+    readonly title: string;
+    /** The default bindings, canonical, in the order the command declares them. */
+    readonly bindings: readonly string[];
+    /** `"panel"`: the bindings apply only while the owner's panel has focus. */
+    readonly focus: "panel" | null;
+}
+/**
+ * The commands the player and its built-in plugins register when the
+ * player starts with nothing open, in menu order (commands outside the main
+ * menu last): their key paths, default bindings and owners. Use it to pick
+ * a menu place and default keys that do not collide with the player's (the
+ * user's own changes come on top; see {@link @vestra-player/sdk!Bindings | Bindings}). Menu items built
+ * from content (tracks, recent files, output devices) are not listed; their
+ * placeholders (`No Audio Tracks`) are. The player's tests check that this
+ * list agrees with what the player and its built-in plugins register.
+ *
+ * @example
+ * ```ts
+ * import assert from "node:assert/strict";
+ * import { BUILTIN_COMMANDS } from "@vestra-player/sdk/testing";
+ *
+ * const taken = BUILTIN_COMMANDS.filter((command) => command.focus === null)
+ *   .flatMap((command) => command.bindings);
+ * assert.ok(!taken.includes("Ctrl+K"));
+ * ```
+ *
+ * @since 1.5.14
+ */
+export declare const BUILTIN_COMMANDS: readonly BuiltinCommand[];
 export type CommandState = {
     enabled: boolean;
     checked: boolean | null;