@vestra-player/sdk 1.5.27 → 1.5.29

package/dist/plugin/types.d.ts

@@ -386,6 +386,77 @@ export type Bindable<T> = T | (() => T);
  * `MENU_IDS` in `@vestra-player/sdk/testing`.
  */
 export type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "screen" | "settings";
+/**
+ * An icon of the player's V-Line set (`@vestra/icons.slint`), by name: what
+ * a bottom-bar button may show. The list is `BAR_BUTTON_ICONS` in
+ * `@vestra-player/sdk/testing`.
+ *
+ * @since 1.5.29
+ */
+export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "open" | "volume" | "mute" | "playlist" | "detach" | "attach" | "close" | "failed" | "move-top" | "move-up" | "move-down" | "move-bottom" | "search" | "chapter" | "bookmark" | "check-task" | "check-box" | "menu-check" | "submenu" | "scroll-up" | "scroll-down" | "caret-down" | "sort-asc" | "sort-desc" | "tag-remove" | "preview-play" | "add" | "remove" | "sort" | "fullscreen" | "exit-fullscreen" | "store" | "ai";
+/**
+ * A command's button on the bottom bar: {@link CommandOptions.button}.
+ *
+ * @remarks
+ * **Where it shows.** The bottom bar places the player's strip of command
+ * buttons, `BarButtons` from `@vestra/bar-buttons.slint`, at its right end;
+ * the player fills it with the buttons of every plugin, left to right by
+ * `order`, and its own sidebar toggle rightmost. When the window is narrow
+ * the strip loses cells from its outer (left) end inward: the lowest order
+ * goes first, the sidebar toggle last. A
+ * bottom bar that does not place `BarButtons` shows no buttons: the
+ * command's menu entry stays, and the player logs the buttons it cannot
+ * show and whose bar hides them. The built-in bar (`vestra.playback`) places
+ * it; see
+ * [Writing a bottom bar](../../docs/guidelines/interface.md#writing-a-bottom-bar).
+ *
+ * **What it shows.** The icon, the command's title (translated, a trailing
+ * "…" removed) and its first key as the tooltip ("Plugin Store (F9)"),
+ * `enabled`, `busy` and `reason` as the menu item has them: a disabled or
+ * busy command's button is drawn disabled, its tooltip adds the reason, and
+ * a click runs nothing. A command with `checked` shows its icon in the
+ * accent colour while checked. A click runs the command exactly like a
+ * click on its menu item.
+ *
+ * **Limits.** One button per plugin and eight in the player
+ * (`BAR_BUTTON_LIMITS`): a button past them is left out (its command and
+ * menu entry stay) and the player logs it with `limit`. The button goes
+ * with its command: disposing the command, or disabling, stopping or
+ * uninstalling the plugin, removes it.
+ *
+ * @example
+ * ```ts
+ * const store = plugin.windows.create("ui/store.slint");
+ * plugin.commands.add({
+ *   id: "open",
+ *   path: ["Plugin Store…"],
+ *   button: { icon: "store", order: 200 },
+ *   run: () => store.show(),
+ * });
+ * ```
+ *
+ * @player 0.5.10; older players show the menu entry without a button
+ * (declare `"minPlayerVersion": "0.5.10"` when the button matters).
+ * @since 1.5.29
+ */
+export interface CommandButton {
+    /**
+     * A name of the player's icon set ({@link BarButtonIcon}), or an image
+     * made with {@link Ui.image} (a PNG or JPEG in your package or data
+     * directory), drawn in the 14×12 icon box, aspect kept, coloured like the
+     * player's line icons: only its alpha counts, so draw it as a dark shape
+     * on a transparent background. An unknown name fails with `invalid`.
+     */
+    icon: BarButtonIcon | ImageRef;
+    /**
+     * Place in the strip, left to right ascending: an integer 0–999. It is
+     * position only: a lower order sits further left, and in a narrow window
+     * (or past the limit of eight) it is the first to go. Equal orders sort
+     * by plugin id, then declaration order. The player's own buttons use AI
+     * 100, Plugin Store 200.
+     */
+    order: number;
+}
 /**
  * The declaration passed to {@link Commands.add}.
  *
@@ -500,6 +571,16 @@ export interface CommandOptions {
     focus?: "panel";
     /** Fire again on keyboard auto-repeat while the key is held. Default false. */
     repeat?: boolean;
+    /**
+     * A button for this command on the bottom bar (SDK 1.5.29, player 0.5.10):
+     * an icon and a place, `{ icon: "store", order: 200 }`. Needs a `path`: the
+     * menu entry is where the command stays reachable when the bar shows no
+     * button (a bar without `BarButtons`, a narrow window, a limit). See
+     * {@link CommandButton} for where it shows, what it shows and the limits.
+     * Fails with `invalid` for an unknown icon name, an order outside 0–999 or
+     * a button without a path.
+     */
+    button?: CommandButton;
     /** Whether the command can run (default true). */
     enabled?: Bindable<boolean>;
     /** Check mark (or radio dot with `radio`); `null` (default) draws none. */

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.27: full reference
+# @vestra-player/sdk 1.5.29: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -498,11 +498,25 @@ The user can rebind any command, the player's own included. Those **overrides**
 - `list()` returns every declared command with its default and current inputs, which of them another command shadows, and the overrides whose command does not exist right now (its plugin is stopped); those are kept and apply again when it returns.
 - To find a command by its place in the menu, compare BindingInfo.key (the English menu keys, the same in every language), not `path`, which is the translated text.
 
+#### Bottom-bar buttons
+
+A command can also be a button on the bottom bar: give it `button: { icon, order }` (CommandButton, player 0.5.10) besides its menu `path`. The player shows the buttons of all plugins in one strip at the bar's right end, left to right by `order`, its own **Toggle Sidebar** rightmost; in a narrow window the lowest order (leftmost) goes first and the toggle last; a click runs the command like its menu item, the tooltip is the item's title and first key, and a disabled or busy command's button is drawn disabled with the reason in its tooltip. One button per plugin and eight in the player (`BAR_BUTTON_LIMITS`). The strip lives in the bottom bar's own layout (`BarButtons`, [Writing a bottom bar): a bar that does not place it shows no buttons, which is why a button always has a menu entry too.
+
+```ts
+const store = plugin.windows.create("ui/store.slint");
+plugin.commands.add({
+  id: "open",
+  path: ["Plugin Store…"],
+  button: { icon: "store", order: 200 },
+  run: () => store.show(),
+});
+```
+
 #### The player's own commands
 
-The player registers some commands itself, with the owner `host`: **Toggle Fullscreen**, **Leave Fullscreen**, **Quit** and the core playback actions (play/pause, stop, previous/next, frame step, relative seek, speed, volume, mute). They exist whether or not any plugin runs, and the user rebinds them like any other command.
+The player registers some commands itself, with the owner `host`: **Toggle Fullscreen**, **Leave Fullscreen**, **Quit**, **Toggle Sidebar** (the bottom bar's sidebar button, player 0.5.10) and the core playback actions (play/pause, stop, previous/next, frame step, relative seek, speed, volume, mute). They exist whether or not any plugin runs, and the user rebinds them like any other command.
 
-A plugin button that does what a core action does should run that action with plugin.host.run (capability `commands`): it applies the same checks and shows the same on-screen text as the menu item and the key, so a bottom bar's play button and the Space key behave identically. The action ids, their menu places and default keys are in [Reference: commands; what they do to playback is in Playback.
+A plugin button that does what a core action does should run that action with plugin.host.run (capability `commands`): it applies the same checks and shows the same on-screen text as the menu item and the key, so a bottom bar's play button and the Space key behave identically. The action ids, their menu places and default keys are in Reference: commands; what they do to playback is in Playback.
 
 ## Concept: Playback state, controls and sources
 
@@ -779,7 +793,7 @@ It assumes you have written a first plugin (Getting started). For every method's
 Two rules of thumb:
 
 - **Prefer the smallest surface that works.** An OSD message before a dialog, a settings page before a tool window. Every window the user has to close is a cost.
-- **Panels are shared space.** There is one sidebar, one bottom bar and one backdrop for all plugins. The sidebar holds several panels as tabs (the player draws the tab strip while there are two or more; showing, hiding and detaching apply to all of them). The bottom bar and the backdrop hold one: while one plugin's panel is there, another plugin's mount rejects with `conflict`, which does not fail its activation. Mount a panel only when the plugin's main purpose is to live there.
+- **Panels are shared space.** There is one sidebar, one bottom bar and one backdrop for all plugins. The sidebar holds several panels as tabs (the player draws the tab strip while there are two or more; showing, hiding and detaching apply to all of them). The bottom bar and the backdrop hold one: while one plugin's panel is there, another plugin's mount rejects with `conflict`, which does not fail its activation. Mount a panel only when the plugin's main purpose is to live there. A command that needs a one-click entry point does not need a panel: give it a bottom-bar button (`button` on commands.add), which the player shows in the strip of command buttons every bottom bar places (Writing a bottom bar).
 
 #### Life cycles
 
@@ -2081,6 +2095,29 @@ The player's picture, audio and subtitle tools share one layout; a window of the
 - **Commands of a panel go into its right-click menu**, made of the plugin's commands (panel.showMenu); see Menus.
 - **The bottom bar is icons only**: no text buttons, no source path, no status text (the source name is in the window title, status is an OSD message).
 
+##### Writing a bottom bar
+
+The bottom bar holds one panel, and every plugin's command buttons (CommandOptions.button) and the player's sidebar toggle show inside it, in a strip the player fills. A bar that replaces the built-in one (`vestra.playback`) must place that strip, or those buttons show nowhere while it is mounted (their menu entries stay):
+
+- **Place `BarButtons`** from `@vestra/bar-buttons.slint` at the right end of the button row, and give it `room`: the width left after your own controls. It shows as many 41×40 cells as fit and loses them from its outer (left) end inward: of the plugins' buttons the lowest order goes first, and the sidebar toggle goes last. The strip is as wide as the cells it shows, so lay your controls out against its `width`. Do not put it under an `if`: it must exist for the player to see it placed. `first-shown` (out) is the index of the leftmost plugin button shown, if your layout needs it.
+- **Decide what goes first when the window narrows.** The built-in bar gives the strip only the room its own buttons and the time leave, so the strip shrinks first, then its Fullscreen button hides, and the time is never cut.
+- **Do not draw a sidebar toggle of your own**: the strip has the player's (**Toggle Sidebar**, `host/sidebar`), with its state.
+- `vestra-plugin check` warns when a plugin mounts a bottom bar whose Slint file does not import `BarButtons` from `@vestra/bar-buttons.slint`, itself or through the plugin's own Slint files it imports, and the player logs the buttons a mounted bar hides.
+
+```slint
+import { BarButtons } from "@vestra/bar-buttons.slint";
+
+export component MyBar inherits Rectangle {
+    height: 40px;
+    // Your controls on the left, 3 × 41px wide …
+    strip := BarButtons {
+        x: root.width - self.width - 4px;
+        y: 0px;
+        room: max(0px, root.width - 3 * 41px - 8px);
+    }
+}
+```
+
 #### Text
 
 - **Every visible text is English source text** that the player translates (Translate a plugin). Write short, plain sentences; one sentence per status or error.
@@ -2102,7 +2139,7 @@ How paths merge, how `order` and `group` sort items and how a key finds its comm
 
 #### Organize by what the user does
 
-- **Put a command where its subject is, not under your plugin's name.** A video filter goes into Video, a subtitle tool into Subtitles, an open-something command into Open. A plugin that brings a domain of its own gets a submenu named after the domain, not after the plugin (the NES plugin's Emulator).
+- **Put a command where its subject is, not under your plugin's name.** A video filter goes into Video, a subtitle tool into Subtitles, an open-something command into Open. A plugin that brings a domain of its own gets a submenu named after the domain, not after the plugin (Games for an emulator, not the emulator's name).
 - **Before adding an item, look for an existing one.** Every command the player and its built-in plugins add, with its menu path and default key, is listed in Built-in commands. Do not add a second entry for something the player already does, and do not scatter one feature over several menus.
 - **Top level is for frequent, direct commands**: opening files, closing, fullscreen and the entries that show a window or panel. Everything else goes into a submenu of its domain.
 - **No "File" or "View" menu.** Commands that open something go into Open ▸; commands that show a window or panel sit directly at the top level.
@@ -2122,7 +2159,6 @@ Playback ▸                                 group domain
 Subtitles ▸
 Video ▸
 Audio ▸
-Emulator ▸
 ────────────────────────────────────────
 Toggle Fullscreen             Enter        group screen
 Screen ▸
@@ -2254,6 +2290,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.2 | HostAction |
 | 0.5.3 | Scrub.seek |
 | 0.5.5 | SessionStorage |
+| 0.5.10 | CommandButton, CommandOptions.button |
 
 The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
 
@@ -2331,6 +2368,16 @@ A command added past a limit fails with code `limit` (its `ready` rejects; durin
 | `COMMAND_LIMITS.perPlugin` | 160 | Commands one plugin instance may have at the same time. |
 | `COMMAND_LIMITS.total` | 1024 | Commands of every plugin plus the player's own, together. |
 
+#### Bottom-bar buttons
+
+A command's button (CommandOptions.button, player 0.5.10) past a limit is left out, not refused: the command registers and its menu entry stays, and the player logs the button with `limit`. Each plugin keeps its first declared button; of those, the player keeps the eight highest orders, so the lowest go first, as in a narrow strip (equal orders: the smaller plugin id, then the earlier declaration, goes first). The player's own sidebar toggle is extra.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `BAR_BUTTON_LIMITS.perPlugin` | 1 | Buttons one plugin shows. |
+| `BAR_BUTTON_LIMITS.total` | 8 | Buttons the player shows, every plugin together, besides its own sidebar toggle. |
+| `BAR_BUTTON_LIMITS.maxOrder` | 999 | The highest `order`. |
+
 #### Property values
 
 One value written to a window, panel or settings page property (View.set, View.bind or an initial property). A value over a limit is refused whole with code `limit`; the property keeps what it showed.
@@ -2491,7 +2538,6 @@ The submenus that exist already, by key path. Write the same keys to add a comma
 | Settings ▸ Appearance | `vestra.preferences`, `vestra.visualizer` |
 | Settings ▸ Language | `vestra.preferences` |
 | Copy to Clipboard | `vestra.playback` |
-| Emulator | `vestra.nes` |
 
 #### Built-in commands
 
@@ -2600,8 +2646,8 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Subtitles ▸ Subtitle Style ▸ Bold | `Alt+B` | `vestra.subtitles/bold` |
 | Subtitles ▸ Subtitle Style ▸ Size + | `Alt+PageUp` | `vestra.subtitles/size-up` |
 | Subtitles ▸ Subtitle Style ▸ Size − | `Alt+PageDown` | `vestra.subtitles/size-down` |
-| Subtitles ▸ Subtitle Style ▸ Move Up | `Alt+ArrowUp` | `vestra.subtitles/move-up` |
-| Subtitles ▸ Subtitle Style ▸ Move Down | `Alt+ArrowDown` | `vestra.subtitles/move-down` |
+| Subtitles ▸ Subtitle Style ▸ Move Up |  | `vestra.subtitles/move-up` |
+| Subtitles ▸ Subtitle Style ▸ Move Down |  | `vestra.subtitles/move-down` |
 | Subtitles ▸ Subtitle Style ▸ Reset Position | `Alt+Home` | `vestra.subtitles/move-reset` |
 | Subtitles ▸ Subtitle Style ▸ Shadow |  | `vestra.subtitles/shadow` |
 | Subtitles ▸ Subtitle Style ▸ Opaque Box |  | `vestra.subtitles/box` |
@@ -2741,9 +2787,6 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Audio ▸ Processing ▸ Crystalizer | `Shift+C` | `vestra.audio/audio.clarity` |
 | Audio ▸ Reset |  | `vestra.audio/audio.reset` |
 | Audio ▸ Show Album Cover for Audio Only |  | `vestra.visualizer/audio-cover` |
-| Emulator ▸ Open NES ROM… |  | `vestra.nes/nes.open` |
-| Emulator ▸ Stop NES |  | `vestra.nes/nes.stop` |
-| Emulator ▸ NES Tools… |  | `vestra.nes/nes.window` |
 | Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11` | `host/fullscreen` |
 | Screen ▸ Picture-in-Picture |  | `vestra.window/pip` |
 | Screen ▸ Mini Size | ``` | `vestra.window/mini` |
@@ -2789,6 +2832,7 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | About Vestra Player… | `F1` | `vestra.info/info.about` |
 | Quit | `Cmd+Q` | `host/quit` |
 | Leave Fullscreen (not in the menu) | `Escape` | `host/exit-fullscreen` |
+| Toggle Sidebar (not in the menu) |  | `host/sidebar` |
 | Brief Info (not in the menu) | `Shift+Tab` | `vestra.info/info.brief` |
 | Play (not in the menu) | `Enter`, `P` (panel focus) | `vestra.playlist/playlist.play` |
 | Add Files… (not in the menu) | `Ctrl+I` (panel focus) | `vestra.playlist/playlist.list-add` |
@@ -2822,6 +2866,23 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Close List (not in the menu) | `F6` (panel focus) | `vestra.playlist/playlist.close` |
 | Playlist Settings… (not in the menu) | `F5` (panel focus) | `vestra.playlist/playlist.settings` |
 
+#### Bottom-bar buttons
+
+`button: { icon, order }` on commands.add (CommandButton, SDK 1.5.29, player 0.5.10) gives a command a button in the bottom bar's strip of command buttons (`BarButtons`, Writing a bottom bar).
+
+| Field | Rule |
+| --- | --- |
+| `icon` | A name of the player's icon set (the names in Theme: Icons, `BAR_BUTTON_ICONS`), or an image from plugin.ui.image drawn in the 14×12 icon box in the icon colour (only its alpha counts). Unknown name: `invalid`. |
+| `order` | Integer 0–999, left to right ascending; equal orders by plugin id, then declaration order. The built-in plugins use 100 (Vestra Player AI) and 200 (Plugin Store). |
+| `path` | Required: a button without a menu path is `invalid`. |
+
+- **Shown**: the icon; the tooltip is the command's shown title without a trailing "…" and its first active key ("Plugin Store (F9)"), plus the reason on a second line while the command is disabled or busy. Disabled or busy: drawn disabled, a click runs nothing. `checked: true`: the icon in the accent colour. Accessibility: a button named by the title, with its enabled and checked state and a default action.
+- **Click**: runs the command exactly as a click on its menu item does.
+- **Order and room**: left to right by `order`, the player's **Toggle Sidebar** rightmost; in a narrow window the strip loses cells from its outer (left) end inward: the lowest order goes first, the sidebar toggle last. `order` is position only: low is further left and goes first.
+- **Limits** (Limits): one button per plugin (its first declared), eight in the player (the highest orders; the lowest go first, ties: the smaller plugin id, then the earlier declaration). A button past them is left out and logged with `limit`; the command and its menu entry stay.
+- **Life cycle**: the button belongs to its command. Disposing the command, or disabling, stopping or uninstalling the plugin, removes it.
+- **Older players** (before 0.5.10) build the declaration with their own copy of the SDK, which does not send `button`: the command and its menu entry work, without a button. Declare `"minPlayerVersion": "0.5.10"` when the button matters.
+
 #### Binding syntax
 
 ```text
@@ -2872,7 +2933,7 @@ The player's own playback commands, which plugin.host.run runs by id (capability
 | `mute` | Audio ▸ Mute | `M` |
 | `fullscreen` | Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11` |
 
-The player also owns **Toggle Fullscreen** (`host/fullscreen`), **Leave Fullscreen** (`host/exit-fullscreen`, `Escape`, only in fullscreen) and **Quit** (`host/quit`); their keys are in Built-in commands.
+The player also owns **Toggle Fullscreen** (`host/fullscreen`), **Leave Fullscreen** (`host/exit-fullscreen`, `Escape`, only in fullscreen) and **Quit** (`host/quit`), and **Toggle Sidebar** (`host/sidebar`, player 0.5.10: the bottom bar's sidebar button, outside the menu, no default key); their keys are in Built-in commands.
 
 #### Keys the system takes first
 
@@ -3047,6 +3108,8 @@ Icon { name: "close"; width: 20px; height: 20px; }         // scaled
 | `sort` | 10 × 10 | 1.5px |
 | `fullscreen` | 14 × 12 | 1.5px |
 | `exit-fullscreen` | 14 × 12 | 1.5px |
+| `store` | 14 × 12 | 1.5px |
+| `ai` | 14 × 12 | 1.5px |
 
 #### Widgets
 
@@ -3128,6 +3191,19 @@ Struct **`MarkdownRow`**: One table row (cells are plain text).
 
 Struct **`MarkdownBlock`**: One displayed block. Plugins only pass these through; the fields are filled by the player.
 
+#### Bar buttons
+
+`@vestra/bar-buttons.slint` (player 0.5.10) is the strip of command buttons a bottom bar places at its right end: the buttons plugins give their commands (CommandOptions.button) and the player's sidebar toggle. The player fills and runs it; the bar only places it and gives it `room`, the width it can spare. See Writing a bottom bar.
+
+**`BarButtons`**: The strip: place it at the bar's right end and give it the width you can spare; it is as wide as the cells it shows (read `width` to lay out the rest).
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `room` | in `length` |  | The width the bar can give the strip; the cells that fit show. |
+| `first-shown` | out `int` | `BarButtonsHost.buttons.length - root.count` | The index (in the player's list, ascending order) of the leftmost plugin button shown; the ones before it are hidden for want of room. |
+
+Struct **`BarButtonItem`**: One button as the player shows it.
+
 ## Reference: Command line
 
 `vestra-plugin` comes with `@vestra-player/sdk` and works in any project that depends on it (`npx vestra-plugin …`, or an npm script). A plugin directory is a directory with `manifest.json`; the default is the current directory, and several can be given at once.
@@ -3499,6 +3575,35 @@ Playback, Subtitles, Video, Audio, Screen, Settings. The list is
 type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "screen" | "settings";
 ```
 
+### BarButtonIcon
+
+An icon of the player's V-Line set (`@vestra/icons.slint`), by name: what
+a bottom-bar button may show. The list is `BAR_BUTTON_ICONS` in
+`@vestra-player/sdk/testing`.
+
+```ts
+type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "open" | "volume" | "mute" | "playlist" | "detach" | "attach" | "close" | "failed" | "move-top" | "move-up" | "move-down" | "move-bottom" | "search" | "chapter" | "bookmark" | "check-task" | "check-box" | "menu-check" | "submenu" | "scroll-up" | "scroll-down" | "caret-down" | "sort-asc" | "sort-desc" | "tag-remove" | "preview-play" | "add" | "remove" | "sort" | "fullscreen" | "exit-fullscreen" | "store" | "ai";
+```
+
+### CommandButton
+
+A command's button on the bottom bar: CommandOptions.button.
+
+- @player 0.5.10; older players show the menu entry without a button (declare `"minPlayerVersion": "0.5.10"` when the button matters).
+
+```ts
+interface CommandButton {
+  /**
+   * A name of the player's icon set (BarButtonIcon), or an image made with Ui.image (a PNG or JPEG in your package or data directory), drawn in the 14×12 icon box, aspect kept, coloured like the player's line icons: only its alpha counts, so draw it as a dark shape on a transparent background. An unknown name fails with `invalid`.
+   */
+  icon: BarButtonIcon | ImageRef;
+  /**
+   * Place in the strip, left to right ascending: an integer 0–999. It is position only: a lower order sits further left, and in a narrow window (or past the limit of eight) it is the first to go. Equal orders sort by plugin id, then declaration order. The player's own buttons use AI 100, Plugin Store 200.
+   */
+  order: number;
+}
+```
+
 ### CommandOptions
 
 The declaration passed to Commands.add.
@@ -3597,6 +3702,10 @@ interface CommandOptions {
   focus?: "panel";
   /** Fire again on keyboard auto-repeat while the key is held. Default false. */
   repeat?: boolean;
+  /**
+   * A button for this command on the bottom bar (SDK 1.5.29, player 0.5.10): an icon and a place, `{ icon: "store", order: 200 }`. Needs a `path`: the menu entry is where the command stays reachable when the bar shows no button (a bar without `BarButtons`, a narrow window, a limit). See CommandButton for where it shows, what it shows and the limits. Fails with `invalid` for an unknown icon name, an order outside 0–999 or a button without a path.
+   */
+  button?: CommandButton;
   /** Whether the command can run (default true). */
   enabled?: Bindable<boolean>;
   /** Check mark (or radio dot with `radio`); `null` (default) draws none. */
@@ -7016,6 +7125,34 @@ interface FakeCommand {
 }
 ```
 
+### FakeBarButton
+
+A command's bottom-bar button (`CommandOptions.button`) as the player shows
+it: an entry of TestHost.barButtons.
+
+```ts
+interface FakeBarButton {
+  /** The command's local id. */
+  readonly command: string;
+  /** The icon name, or the image's path for a `plugin.ui.image` icon. */
+  readonly icon: string;
+  /** `true` when the icon is the plugin's image. */
+  readonly image: boolean;
+  /** The declared `order`. */
+  readonly order: number;
+  /** Clickable: the command is enabled and not busy. */
+  readonly enabled: boolean;
+  /** Drawn in the accent colour: the command is checked. */
+  readonly checked: boolean;
+  /** The tooltip without the key: the command's shown title (trailing "…" removed), then, while it cannot run, its reason on a second line. */
+  readonly tooltip: string;
+  /**
+   * Click the button, then wait until the host is idle: runs the command as its menu item would. Rejects (with a HostError) while the button is disabled, and once the command is gone.
+   */
+  click(): Promise<void>;
+}
+```
+
 ### FakeProducer
 
 A generated stream (`plugin.player.openStream`) as the test host sees it:
@@ -7815,6 +7952,10 @@ class TestHost implements Transport {
   step(direction: "next" | "previous"): Promise<unknown>;
   /** The plugin's command with this local id. Throws when it is not registered (never added, or disposed). */
   command(id: string): FakeCommand;
+  /**
+   * The plugin's bottom-bar buttons (`CommandOptions.button`) as the player shows them: at most one, the first declared (`BAR_BUTTON_LIMITS`; a later one stays a menu item only). Empty once the command is disposed. Whether the bar places them is the bar's business: the list is what the player hands to `BarButtons`.
+   */
+  get barButtons(): readonly FakeBarButton[];
   /**
    * The plugin's tool window with this id (by default the file name without extension: `ui/picture.slint` → `picture`). Throws when it was never opened with `show()`.
    */
@@ -7996,6 +8137,39 @@ agrees with the player's.
 const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings"];
 ```
 
+### BAR_BUTTON_ICONS
+
+The icons a bottom-bar button may name (`CommandOptions.button.icon`):
+every icon of the player's V-Line set, `@vestra/icons.slint` (draw one
+in your own Slint with `Icon { name: "store"; }`). The player's tests check
+that this list is its icon set.
+
+```ts
+const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back", "forward", "open", "volume", "mute", "playlist", "detach", "attach", "close", "failed", "move-top", "move-up", "move-down", "move-bottom", "search", "chapter", "bookmark", "check-task", "check-box", "menu-check", "submenu", "scroll-up", "scroll-down", "caret-down", "sort-asc", "sort-desc", "tag-remove", "preview-play", "add", "remove", "sort", "fullscreen", "exit-fullscreen", "store", "ai"];
+```
+
+### BAR_BUTTON_LIMITS
+
+The player's limits on bottom-bar buttons (`CommandOptions.button`), the
+same values as the player's (its tests check that they agree). A button
+past `perPlugin` or `total` is left out: its command still registers and
+its menu entry stays, and the player logs the button it left out
+(`limit`). Which ones stay: each plugin's first declared button, then the
+`total` highest by order, plugin id and declaration order: as in a narrow
+strip, the lowest order goes first (equal orders: the smaller plugin id,
+then the earlier declaration, goes first).
+
+```ts
+const BAR_BUTTON_LIMITS: {
+  /** Buttons one plugin shows (1). */
+  readonly perPlugin: 1;
+  /** Buttons the player shows, every plugin together, besides its own sidebar toggle (8). */
+  readonly total: 8;
+  /** The highest `order` (999; the lowest is 0). */
+  readonly maxOrder: 999;
+};
+```
+
 ### BuiltinSubmenu
 
 A submenu that one of the player's built-in plugins declares: an entry of
@@ -8688,6 +8862,13 @@ type CommandDeclaration = {
   focus: "panel" | null;
   /** Fire again on keyboard auto-repeat while held. */
   repeat: boolean;
+  /**
+   * A bottom-bar button (player 0.5.10): an icon name, or an image in the `plugin.ui.image` wire form. Sent only when set: older players refuse unknown declaration fields.
+   */
+  button?: {
+    icon: string | Json;
+    order: number;
+  };
 };
 ```
 

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.27: 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; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
+> @vestra-player/sdk 1.5.29: 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; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
 
 **Rules**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2195–2261.
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2231–2298.
 
 **main.ts**
 
@@ -76,9 +76,9 @@ export default async function activate(plugin: Plugin) {
 - `ui.settings`: Settings.page/show
 - `ui.theme`: Appearance.set/setLanguage
 - `secrets`: Secrets.get/set/delete
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2262–2320.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2299–2357.
 
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`; `host` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1658–1846; TestHost: L7061.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`; `host` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1672–1860; TestHost: L7198.
 
 **Command line**
 
@@ -106,39 +106,39 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player or another `apiVersion`
-- Others: PluginError, llms-full.txt L3231.
+- Others: PluginError, llms-full.txt L3307.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; the pages are on the [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–237
-- Concepts: How a plugin runs L238–408; Commands, menus and key bindings L409–506; Playback state, controls and sources L507–652; Video and audio processing L653–731; Windows, panels, settings pages, dialogs and the OSD L732–1020
-- How-to: Keep a slider responsive while dragging L1021–1195; Remember a window's state between runs L1196–1325; Translate a plugin L1326–1509; Migrate a plugin to English source text L1510–1657; Test a plugin L1658–1846; Publish a plugin L1847–1935; Migrating off package rollback (1.5.16, removed in 1.5.17) L1936–2011
-- Guidelines: Interface guidelines L2012–2096; Menu guidelines L2097–2194
-- Reference: Manifest L2195–2261; Capabilities L2262–2320; Limits L2321–2425; Commands, menus and bindings L2426–2894; Platforms L2895–2923; Theme L2924–3130; Command line L3131–3188
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3189–6896
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6897–8302
+- Concepts: How a plugin runs L238–408; Commands, menus and key bindings L409–520; Playback state, controls and sources L521–666; Video and audio processing L667–745; Windows, panels, settings pages, dialogs and the OSD L746–1034
+- How-to: Keep a slider responsive while dragging L1035–1209; Remember a window's state between runs L1210–1339; Translate a plugin L1340–1523; Migrate a plugin to English source text L1524–1671; Test a plugin L1672–1860; Publish a plugin L1861–1949; Migrating off package rollback (1.5.16, removed in 1.5.17) L1950–2025
+- Guidelines: Interface guidelines L2026–2133; Menu guidelines L2134–2230
+- Reference: Manifest L2231–2298; Capabilities L2299–2357; Limits L2358–2472; Commands, menus and bindings L2473–2955; Platforms L2956–2984; Theme L2985–3206; Command line L3207–3264
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3265–7005
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L7006–8476
 
 ## API
 
 Where each module of `plugin` (`plugin.<module>`) is declared:
 
-- Plugin L3423, Scope L3292, PluginError L3231, Disposable L3204
-- Commands L3635; Windows L3865; Panels L4508; Dialogs L4794; Player L5261; video: VideoFilter L5568, VideoView L5631, RenderOptions L5673; audio: AudioFilter L5592; Subtitles L5771; media: MediaCapture L5932; Resolvers L6037; Packages L6279; Osd L5504; Host L5435; Clipboard L6411; Power L6431; Tools L6464; Storage L6507; System L6594; Secrets L6612; window: MainWindow L4631; App L4712; Bindings L6381; Ui L3740; Timeline L4588; Drops L4164; Appearance L4193; I18n L4335; Settings L4441.
+- Plugin L3499, Scope L3368, PluginError L3307, Disposable L3280
+- Commands L3744; Windows L3974; Panels L4617; Dialogs L4903; Player L5370; video: VideoFilter L5677, VideoView L5740, RenderOptions L5782; audio: AudioFilter L5701; Subtitles L5880; media: MediaCapture L6041; Resolvers L6146; Packages L6388; Osd L5613; Host L5544; Clipboard L6520; Power L6540; Tools L6573; Storage L6616; System L6703; Secrets L6721; window: MainWindow L4740; App L4821; Bindings L6490; Ui L3849; Timeline L4697; Drops L4273; Appearance L4302; I18n L4444; Settings L4550.
 
 ## Examples
 
 Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L8726–8815
-- blur: A tool window with one slider that blurs the playing video. L8816–9077
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L9078–9410
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9411–9595
-- panel-menu: A sidebar panel with its own right-click menu. L9596–9801
-- menus: Radio menu items, separator groups and a menu item whose title changes. L9802–9961
-- theme-widgets: A tool window drawn with the player's theme and widgets. L9962–10125
-- markdown: A window that shows a Markdown document. L10126–10320
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L10321–10488
+- hello: The README Quick start: one menu command and an on-screen message. L8907–8996
+- blur: A tool window with one slider that blurs the playing video. L8997–9258
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L9259–9591
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9592–9776
+- panel-menu: A sidebar panel with its own right-click menu. L9777–9982
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9983–10142
+- theme-widgets: A tool window drawn with the player's theme and widgets. L10143–10306
+- markdown: A window that shows a Markdown document. L10307–10501
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L10502–10669
 
 ## Optional
 

package/package.json

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