@vestra-player/sdk 1.5.28 → 1.5.29

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.5.29
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. A plugin that does not use `button` is unaffected. A plugin that uses it on a player before 0.5.10 keeps working without a button: the player builds the `plugin` object with its own SDK copy, which does not send the field, so the command and its menu entry register as before (declare `"minPlayerVersion": "0.5.10"` when the button matters). A plugin that mounts its own bottom bar should place `BarButtons` (below); until it does, `vestra-plugin check` warns and the player logs the buttons it hides.
+
+- **Commands can have a bottom-bar button** (player 0.5.10, user-approved design of 2026-10-27): `button: { icon, order }` on `commands.add` (`CommandOptions.button`, `CommandButton`, `BarButtonIcon`). The icon is a name of the player's icon set or an image from `plugin.ui.image` (drawn in the icon colour); `order` 0–999 places it left to right. The button needs a menu `path`; its tooltip is the command's title (without a trailing "…") and first key; disabled or busy commands show a disabled button with the reason; a click runs the command like its menu item. One button per plugin, eight in the player (`BAR_BUTTON_LIMITS`; past eight the highest orders stay and the lowest go first, ties: the smaller plugin id, then the earlier declaration); a button past them is left out (the command and its menu entry stay) and the player logs it with `limit`. `add` throws `invalid` for an unknown icon name (`BAR_BUTTON_ICONS`), an order outside 0–999, a released image or a button without a path.
+- **`@vestra/bar-buttons.slint`**: `BarButtons`, the strip of command buttons a bottom bar places at its right end with `room`, the width it can spare. It shows the cells that fit (the player's sidebar toggle, **Toggle Sidebar** `host/sidebar`, rightmost and last to go; cells go from the strip's outer (left) end inward, so of the plugins' buttons the lowest order goes first; `order` is position only) and is as wide as the cells it shows (`first-shown`, out, is the index of the leftmost plugin button shown). The player fills it in every window it composes and runs the clicks. Slint library copy synced; the icon set gains `store` (a shopping bag) and `ai` (a sparkle).
+- **`TestHost.barButtons`**: the plugin's button as the player shows it (`command`, `icon`, `image`, `order`, `enabled`, `checked`, `tooltip`) with `click()`, which runs the command and rejects while it is disabled or once it is gone; empty after the command is disposed. The test host checks buttons as the player does.
+- **`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 (comments do not count; a warning, the check still passes).
+- `BUILTIN_COMMANDS` gains the player's **Toggle Sidebar** (`host/sidebar`, outside the menu, no default key).
+- Docs: *Commands* (concepts) gains *Bottom-bar buttons*; *Commands, menus and bindings* (reference) gains *Bottom-bar buttons*; *Interface guidelines* gains *Writing a bottom bar*; *Limits* gains *Bottom-bar buttons*; *Theme* gains *Bar buttons* and the two icons; *Windows, panels…* points to buttons for a one-click entry point. `llms.txt` and `llms-full.txt` regenerated.
+
 ## 1.5.28
 
 **Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`. Only the SDK's copy of what the player ships changes; a plugin that read `BUILTIN_COMMANDS` or `BUILTIN_SUBMENUS` to avoid a key or a menu path simply finds those entries free now.

package/bin/vestra-plugin.mjs

@@ -75,6 +75,7 @@ import {
   basename,
   dirname,
   extname,
+  isAbsolute,
   join,
   relative,
   resolve,
@@ -356,6 +357,8 @@ async function check(target, report = null) {
   }
   say(`${target.name}: capabilities declared for every API use`);
   if (report) return;
+  for (const line of await bottomBarWarnings(target))
+    console.log(`${target.name}: warning: ${line}`);
   // Translation warnings never fail the check.
   if (present(join(target.directory, "locales"))) {
     try {
@@ -399,6 +402,106 @@ async function capabilityFindings(target, config) {
     .map((finding) => ({ ...finding, file: resolve(finding.file) }));
 }
 
+/** Slint source without its comments (string literals kept as they are). */
+function slintCode(text) {
+  let out = "";
+  for (let i = 0; i < text.length;) {
+    if (text[i] === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+      out += text.slice(i, j + 1);
+      i = j + 1;
+    } else if (text.startsWith("//", i)) {
+      const next = text.indexOf("\n", i);
+      i = next < 0 ? text.length : next;
+    } else if (text.startsWith("/*", i)) {
+      const close = text.indexOf("*/", i + 2);
+      i = close < 0 ? text.length : close + 2;
+      out += " ";
+    } else out += text[i++];
+  }
+  return out;
+}
+
+/** Whether `path` lies inside `directory` (not a sibling sharing its prefix). */
+function inside(directory, path) {
+  const rel = relative(resolve(directory), path);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Whether the Slint file at `file` (relative to the plugin directory)
+ * imports `BarButtons` from `@vestra/bar-buttons.slint`, itself or
+ * through the plugin's own Slint files (relative paths, any depth, inside
+ * the plugin directory). Local re-exports count as such files too:
+ * `export { Row } from "row.slint"` and `export * from "row.slint"` are
+ * followed, and `export { BarButtons } from "@vestra/bar-buttons.slint"` (or
+ * `export * from` it) in a file the bar imports counts as placing it.
+ * Comments do not count.
+ */
+async function importsBarButtons(target, file, seen = new Set()) {
+  const path = resolve(target.directory, file);
+  if (seen.has(path) || !inside(target.directory, path)) return false;
+  seen.add(path);
+  const text = await readFile(path, "utf8").catch(() => null);
+  if (text === null) return false;
+  const code = slintCode(text);
+  // { names (or "*"), from }: imports, and re-exports with a source file.
+  const imports = [
+    ...code.matchAll(
+      /\b(?:import|export)\s*(?:(\*)\s*from\s*|\{([^}]*)\}\s*from\s*)?"([^"]+)"/g,
+    ),
+  ].map(([, star, names, from]) => ({ names: star ?? names ?? "", from }));
+  for (const { names, from } of imports)
+    if (
+      from === "@vestra/bar-buttons.slint" &&
+      (names === "*" ||
+        names
+          .split(",")
+          .some((name) => /^BarButtons(\s+as\s+[\w-]+)?$/.test(name.trim())))
+    )
+      return true;
+  for (const { from } of imports) {
+    if (
+      from.startsWith("@") ||
+      !from.endsWith(".slint") ||
+      from === "std-widgets.slint"
+    )
+      continue;
+    if (await importsBarButtons(target, join(dirname(file), from), seen))
+      return true;
+  }
+  return false;
+}
+
+/**
+ * A plugin that mounts a bottom bar (`panels.mount("bottom", "<file>")`)
+ * whose Slint file does not import `BarButtons` (`@vestra/bar-buttons.slint`),
+ * itself or through its local imports: while it is the bottom bar, no
+ * plugin's command button shows (SDK 1.5.29). The mount is read from the
+ * source text: a literal file name in the call.
+ */
+async function bottomBarWarnings(target) {
+  const { typescript: sources } = await sourceFiles(target);
+  const files = new Set();
+  for (const file of sources) {
+    const text = await readFile(join(target.directory, file), "utf8");
+    for (const match of text.matchAll(
+      /\.mount\(\s*["'`]bottom["'`]\s*,\s*["'`]([^"'`$]+)["'`]/g,
+    ))
+      files.add(match[1]);
+  }
+  const warnings = [];
+  for (const file of files) {
+    if (!present(join(target.directory, file))) continue;
+    if (await importsBarButtons(target, file)) continue;
+    warnings.push(
+      `${file} is a bottom bar without BarButtons (import { BarButtons } from "@vestra/bar-buttons.slint"): while it is mounted, the command buttons of every plugin (and the player's sidebar toggle) show nowhere; see docs/guidelines/interface.md#writing-a-bottom-bar`,
+    );
+  }
+  return warnings;
+}
+
 /** The plugin's own production .ts / .mts and .slint files. */
 async function sourceFiles(target) {
   const all = await files(target.directory);

package/dist/commands.d.ts

@@ -1,5 +1,5 @@
 /** Finite candidate command registry. Host authenticates owner; no plugin supplies an owner id. */
-import type { Transport } from "./wire.ts";
+import type { Json, Transport } from "./wire.ts";
 import type { ListJson, TextJson } from "./i18n.ts";
 /**
  * The player's command registry caps, the same values as the player's own
@@ -44,6 +44,43 @@ export declare const COMMAND_LIMITS: {
  * ```
  */
 export declare const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings"];
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import assert from "node:assert/strict";
+ * import { BAR_BUTTON_ICONS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(BAR_BUTTON_ICONS.includes("store"));
+ * ```
+ *
+ * @since 1.5.29
+ */
+export declare 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"];
+/**
+ * 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).
+ *
+ * @since 1.5.29
+ */
+export declare 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;
+};
 /**
  * A submenu that one of the player's built-in plugins declares: an entry of
  * {@link BUILTIN_SUBMENUS}.
@@ -157,6 +194,15 @@ export 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;
+    };
 };
 export declare function commandClient(transport: Transport): {
     register: (id: string, revision: number, declaration: CommandDeclaration, state: CommandState) => Promise<{

package/dist/commands.js

@@ -49,6 +49,82 @@ export const MENU_IDS = [
     "screen",
     "settings",
 ];
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import assert from "node:assert/strict";
+ * import { BAR_BUTTON_ICONS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(BAR_BUTTON_ICONS.includes("store"));
+ * ```
+ *
+ * @since 1.5.29
+ */
+export const BAR_BUTTON_ICONS = [
+    "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",
+];
+/**
+ * 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).
+ *
+ * @since 1.5.29
+ */
+export const BAR_BUTTON_LIMITS = {
+    /** Buttons one plugin shows (1). */
+    perPlugin: 1,
+    /** Buttons the player shows, every plugin together, besides its own sidebar toggle (8). */
+    total: 8,
+    /** The highest `order` (999; the lowest is 0). */
+    maxOrder: 999,
+};
 /**
  * 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).
@@ -413,6 +489,7 @@ vestra.preferences | language.es | Settings ▸ Language ▸ Español
 vestra.info | info.about | About Vestra Player… | F1
 host | quit | Quit | Cmd+Q
 host | exit-fullscreen | (Leave Fullscreen) | Escape
+host | sidebar | (Toggle Sidebar)
 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/player-runtime.d.ts

@@ -13,7 +13,7 @@ export { HostError } from "./wire.ts";
 export type { Json, Transport } from "./wire.ts";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.ts";
 export { HOST_CAPABILITIES } from "./host-capabilities.ts";
-export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.ts";
+export { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.ts";
 export { BINDING_INPUTS } from "./plugin/bindings.ts";
 export { OSD_LIMITS } from "./plugin/osd.ts";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.ts";

package/dist/player-runtime.js

@@ -11,7 +11,7 @@ export { createPlugin } from "./plugin/index.js";
 export { HostError } from "./wire.js";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.js";
 export { HOST_CAPABILITIES } from "./host-capabilities.js";
-export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.js";
+export { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.js";
 export { BINDING_INPUTS } from "./plugin/bindings.js";
 export { OSD_LIMITS } from "./plugin/osd.js";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.js";

package/dist/plugin/commands.js

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

package/dist/plugin/testing.d.ts

@@ -2,7 +2,7 @@ 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 { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS } from "../commands.ts";
+import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, 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";
@@ -22,6 +22,8 @@ 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 icons and limits of bottom-bar buttons, which the test host checks as well. */
+export { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS };
 /** The submenus of the player's built-in plugins, by key path. */
 export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS };
 export type { BuiltinCommand, BuiltinSubmenu };
@@ -199,6 +201,37 @@ export interface FakeCommand {
      */
     run(): Promise<void>;
 }
+/**
+ * A command's bottom-bar button (`CommandOptions.button`) as the player shows
+ * it: an entry of {@link TestHost.barButtons}.
+ *
+ * @since 1.5.29
+ */
+export 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 {@link HostError}) while the
+     * button is disabled, and once the command is gone.
+     */
+    click(): Promise<void>;
+}
 /**
  * A generated stream (`plugin.player.openStream`) as the test host sees it:
  * the fake player end of the frame connection. Assertion surface; see
@@ -1477,6 +1510,24 @@ export declare class TestHost implements Transport {
      * 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`.
+     *
+     * @example
+     * ```ts
+     * const [button] = host.barButtons;
+     * assert.equal(button?.icon, "store");
+     * await button?.click();
+     * assert.equal(host.window("store").visible, true);
+     * ```
+     *
+     * @since 1.5.29
+     */
+    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

package/dist/plugin/testing.js

@@ -66,7 +66,7 @@ import { extname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HostError } from "../wire.js";
 import { localSocketPath } from "./local.js";
-import { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "../commands.js";
+import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, 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, SESSION_STORAGE_LIMITS } from "./services.js";
@@ -83,6 +83,8 @@ 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 icons and limits of bottom-bar buttons, which the test host checks as well. */
+export { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS };
 /** 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. */
@@ -2095,6 +2097,53 @@ export class TestHost {
             throw new Error(`command ${id} is not registered`);
         return command;
     }
+    /**
+     * 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`.
+     *
+     * @example
+     * ```ts
+     * const [button] = host.barButtons;
+     * assert.equal(button?.icon, "store");
+     * await button?.click();
+     * assert.equal(host.window("store").visible, true);
+     * ```
+     *
+     * @since 1.5.29
+     */
+    get barButtons() {
+        const host = this;
+        return [...this.commands]
+            .filter(([, command]) => command.declaration.button !== undefined)
+            .slice(0, BAR_BUTTON_LIMITS.perPlugin)
+            .map(([id, command]) => {
+            const button = command.declaration.button;
+            const image = typeof button.icon !== "string";
+            const reason = command.display.reason;
+            const title = command.display.title.replace(/(…|\.\.\.)\s*$/, "");
+            const enabled = command.state.enabled && !command.state.busy;
+            return Object.freeze({
+                command: id,
+                icon: image
+                    ? String(button.icon.$vestraImage)
+                    : button.icon,
+                image,
+                order: button.order,
+                enabled,
+                checked: command.state.checked === true,
+                tooltip: !enabled && reason ? `${title}\n${reason}` : title,
+                async click() {
+                    const current = host.commands.get(id);
+                    if (current !== command)
+                        throw new HostError("missing", `command ${id} is gone`);
+                    await current.run();
+                },
+            });
+        });
+    }
     /**
      * The plugin's tool window with this id (by default the file name without
      * extension: `ui/picture.slint` → `picture`). Throws when it was never
@@ -2501,6 +2550,23 @@ export class TestHost {
                 throw new HostError("limit", "command registry limit reached");
             const host = this;
             const declaration = p.declaration;
+            // Player 0.5.10: a bar button needs a path, an order 0–999 and a
+            // known icon or an image of the plugin.
+            if (declaration.button !== undefined) {
+                const { icon, order } = declaration.button;
+                if (path.length === 0)
+                    throw new HostError("invalid", "button needs a menu path");
+                if (!Number.isInteger(order) ||
+                    order < 0 ||
+                    order > BAR_BUTTON_LIMITS.maxOrder)
+                    throw new HostError("invalid", `button order must be an integer 0–${BAR_BUTTON_LIMITS.maxOrder}`);
+                if (typeof icon === "string") {
+                    if (!BAR_BUTTON_ICONS.includes(icon))
+                        throw new HostError("invalid", `unknown button icon "${icon}"`);
+                }
+                else if (this.imagePath(icon) === null)
+                    throw new HostError("invalid", "button icon is an icon name or an image from plugin.ui.image");
+            }
             // Like the player: the menu texts and the reason are checked (and
             // shown) when they arrive.
             for (const segment of [declaration.title, ...(declaration.path ?? [])])

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.28: 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.
@@ -2253,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).
 
@@ -2330,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.
@@ -2784,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` |
@@ -2817,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
@@ -2867,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
 
@@ -3042,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
 
@@ -3123,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.
@@ -3494,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.
@@ -3592,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. */
@@ -7011,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:
@@ -7810,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()`.
    */
@@ -7991,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
@@ -8683,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.28: 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: L2194–2260.
+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: L2261–2319.
+- 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: L7056.
+**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 L3226.
+- 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–2193
-- Reference: Manifest L2194–2260; Capabilities L2261–2319; Limits L2320–2424; Commands, menus and bindings L2425–2889; Platforms L2890–2918; Theme L2919–3125; Command line L3126–3183
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3184–6891
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6892–8297
+- 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 L3418, Scope L3287, PluginError L3226, Disposable L3199
-- Commands L3630; Windows L3860; Panels L4503; Dialogs L4789; Player L5256; video: VideoFilter L5563, VideoView L5626, RenderOptions L5668; audio: AudioFilter L5587; Subtitles L5766; media: MediaCapture L5927; Resolvers L6032; Packages L6274; Osd L5499; Host L5430; Clipboard L6406; Power L6426; Tools L6459; Storage L6502; System L6589; Secrets L6607; window: MainWindow L4626; App L4707; Bindings L6376; Ui L3735; Timeline L4583; Drops L4159; Appearance L4188; I18n L4330; Settings L4436.
+- 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. L8721–8810
-- blur: A tool window with one slider that blurs the playing video. L8811–9072
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L9073–9405
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9406–9590
-- panel-menu: A sidebar panel with its own right-click menu. L9591–9796
-- menus: Radio menu items, separator groups and a menu item whose title changes. L9797–9956
-- theme-widgets: A tool window drawn with the player's theme and widgets. L9957–10120
-- markdown: A window that shows a Markdown document. L10121–10315
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L10316–10483
+- 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.28",
+  "version": "1.5.29",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {

package/slint/vestra/bar-buttons.slint

@@ -0,0 +1,138 @@
+// Command buttons of a bottom bar (player 0.5.10, SDK 1.5.29): the buttons
+// that plugins' commands contribute (`commands.add({ button })`) and the
+// player's sidebar toggle, rightmost. The player fills `BarButtonsHost` in
+// every window it composes and runs the clicks; a bottom bar places one
+// `BarButtons` in its own layout and gives it the width it can spare:
+//   import { BarButtons } from "@vestra/bar-buttons.slint";
+//   strip := BarButtons { x: parent.width - self.width - 4px; room: ...; }
+// It shows as many 41×40 cells as fit in `room`, the strip as wide as the
+// cells shown (`width`). Cells go from the strip's outer (left) end inward:
+// of the plugins' buttons (ascending `order`, left to right) the lowest
+// order goes first, and the sidebar toggle goes last. A bar without a `BarButtons` shows none of them (their menu
+// entries stay; the player logs which buttons are hidden).
+//
+// The cells look like the bar's own icon buttons: a 32×32 plate on hover
+// and press, the V-Line icon in the text colour (accent while a toggle is
+// on), the bar's tooltip (ToolTipArea). They are persistent elements shown with
+// `visible:`; nothing is created on hover or resize.
+import { Theme } from "theme.slint";
+import { Icon } from "icons.slint";
+import { ToolTipArea } from "widgets.slint";
+
+// One button as the player shows it.
+export struct BarButtonItem {
+    // What a click runs (the player's own token; "" for no button).
+    token: string,
+    // A name of @vestra/icons.slint, or "" for `image`.
+    icon: string,
+    // The plugin's image (`plugin.ui.image`), drawn in the icon colour.
+    image: image,
+    // The command's title (the accessibility label).
+    label: string,
+    // The tooltip: the title and its key, the reason it is unavailable.
+    tip: string,
+    enabled: bool,
+    // The command has a checked state; `checked` draws the icon in the accent.
+    checkable: bool,
+    checked: bool,
+    // At half opacity: on, but not shown for want of room (the sidebar).
+    dimmed: bool,
+}
+
+// Filled by the player; a bar reads it only through `BarButtons`.
+export global BarButtonsHost {
+    // The plugins' buttons, left to right, at most 8.
+    in property <[BarButtonItem]> buttons;
+    // The sidebar toggle (`token` "" while there is none).
+    in property <BarButtonItem> toggle;
+    // Set when a `BarButtons` exists in this window.
+    in-out property <bool> placed;
+    // A click on the cell with this token.
+    callback clicked(string);
+}
+
+// One 41×40 cell (the bar's BarButton). `shown`: on screen; a hidden cell
+// is not actionable from the accessibility tree either.
+component Cell inherits Rectangle {
+    in property <BarButtonItem> item;
+    in property <bool> shown;
+    private property <bool> live: root.shown && root.item.enabled;
+    private property <brush> tint: !root.item.enabled ? Theme.icon-disabled
+        : root.item.checked ? (touch.pressed ? Theme.accent-press : Theme.accent)
+        : Theme.text;
+    width: 41px;
+    height: 40px;
+    visible: root.shown;
+    opacity: root.item.dimmed ? 0.5 : 1;
+    accessible-role: button;
+    accessible-label: root.item.label;
+    accessible-description: root.item.tip;
+    accessible-enabled: root.live;
+    accessible-checkable: root.item.checkable;
+    accessible-checked: root.item.checked;
+    accessible-action-default => { if root.live { BarButtonsHost.clicked(root.item.token); } }
+    Rectangle {
+        x: 4px;
+        y: 4px;
+        width: parent.width - 9px;
+        height: parent.height - 8px;
+        border-radius: Theme.radius-panel;
+        background: !root.live ? transparent
+            : touch.pressed ? Theme.press-bg
+            : touch.has-hover ? Theme.hover-bg : transparent;
+    }
+    Icon {
+        visible: root.item.icon != "";
+        x: (root.width - 1px - self.width) / 2;
+        y: (root.height - self.height) / 2;
+        name: root.item.icon;
+        color: root.tint;
+    }
+    // A plugin's image in the icon box (14×12), aspect kept, coloured like the icons.
+    Image {
+        visible: root.item.icon == "";
+        x: (root.width - 1px - self.width) / 2;
+        y: (root.height - self.height) / 2;
+        width: 14px;
+        height: 12px;
+        source: root.item.image;
+        image-fit: contain;
+        colorize: root.tint;
+    }
+    ToolTipArea {
+        width: 100%;
+        height: 100%;
+        text: root.shown ? root.item.tip : "";
+        touch := TouchArea {
+            enabled: root.live;
+            clicked => { BarButtonsHost.clicked(root.item.token); }
+        }
+    }
+}
+
+// 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).
+export component BarButtons {
+    // The width the bar can give the strip; the cells that fit show.
+    in property <length> room;
+    // 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.
+    out property <int> first-shown: BarButtonsHost.buttons.length - root.count;
+    // The cells that fit in `room`.
+    private property <int> fit: Math.max(0, Math.floor(root.room / 41px));
+    private property <bool> toggle: BarButtonsHost.toggle.token != "" && root.fit >= 1;
+    // The plugins' buttons shown: the highest orders, left of the toggle's cell.
+    private property <int> count: Math.max(0, Math.min(BarButtonsHost.buttons.length, root.fit - (root.toggle ? 1 : 0)));
+    width: (root.count + (root.toggle ? 1 : 0)) * 41px;
+    height: 40px;
+    init => { BarButtonsHost.placed = true; }
+    Cell { x: (0 - root.first-shown) * 41px; shown: 0 >= root.first-shown && 0 < BarButtonsHost.buttons.length; item: BarButtonsHost.buttons[0]; }
+    Cell { x: (1 - root.first-shown) * 41px; shown: 1 >= root.first-shown && 1 < BarButtonsHost.buttons.length; item: BarButtonsHost.buttons[1]; }
+    Cell { x: (2 - root.first-shown) * 41px; shown: 2 >= root.first-shown && 2 < BarButtonsHost.buttons.length; item: BarButtonsHost.buttons[2]; }
+    Cell { x: (3 - root.first-shown) * 41px; shown: 3 >= root.first-shown && 3 < BarButtonsHost.buttons.length; item: BarButtonsHost.buttons[3]; }
+    Cell { x: (4 - root.first-shown) * 41px; shown: 4 >= root.first-shown && 4 < BarButtonsHost.buttons.length; item: BarButtonsHost.buttons[4]; }
+    Cell { x: (5 - root.first-shown) * 41px; shown: 5 >= root.first-shown && 5 < BarButtonsHost.buttons.length; item: BarButtonsHost.buttons[5]; }
+    Cell { x: (6 - root.first-shown) * 41px; shown: 6 >= root.first-shown && 6 < BarButtonsHost.buttons.length; item: BarButtonsHost.buttons[6]; }
+    Cell { x: (7 - root.first-shown) * 41px; shown: 7 >= root.first-shown && 7 < BarButtonsHost.buttons.length; item: BarButtonsHost.buttons[7]; }
+    Cell { x: root.count * 41px; shown: root.toggle; item: BarButtonsHost.toggle; }
+}

package/slint/vestra/icons.slint

@@ -48,6 +48,10 @@ export global Icons {
         // Four corners pointing out (enter) or in (leave), the default 14 × 12 box.
         if name == "fullscreen" { return "M 1.5 4.5 V 1.5 H 4.5 M 9.5 1.5 H 12.5 V 4.5 M 12.5 7.5 V 10.5 H 9.5 M 4.5 10.5 H 1.5 V 7.5"; }
         if name == "exit-fullscreen" { return "M 4.5 1.5 V 4.5 H 1.5 M 9.5 1.5 V 4.5 H 12.5 M 12.5 7.5 H 9.5 V 10.5 M 1.5 7.5 H 4.5 V 10.5"; }
+        // A shopping bag (the plugin store) and a four-point sparkle with a
+        // small cross (AI), the default 14 × 12 box; bar buttons use them.
+        if name == "store" { return "M 2.5 4 H 11.5 L 10.9 9.6 Q 10.8 10.5 9.9 10.5 H 4.1 Q 3.2 10.5 3.1 9.6 Z M 5.2 4 V 3.3 A 1.8 1.8 0 0 1 8.8 3.3 V 4"; }
+        if name == "ai" { return "M 6 1.5 Q 6.6 5.4 10.5 6 Q 6.6 6.6 6 10.5 Q 5.4 6.6 1.5 6 Q 5.4 5.4 6 1.5 Z M 11.5 1.2 V 3.8 M 10.2 2.5 H 12.8"; }
         return "";
     }
     // Line width.