@vestra-player/sdk 1.5.27 → 1.5.29

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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.
+
+- **`BUILTIN_COMMANDS` and `BUILTIN_SUBMENUS` follow the player** (its agreement test failed on them):
+  - Subtitles 0.4.6: `vestra.subtitles` **Move Up** and **Move Down** have no default keys any more (they were `Alt+ArrowUp` / `Alt+ArrowDown`, which pan the video).
+  - The NES emulator is no longer a built-in plugin (it moved to the plugin repository as VestraNES, under **Games ▸ VestraNES**): its three commands (`nes.open`, `nes.stop`, `nes.window`) and the built-in **Emulator** submenu are gone. The player has no built-in Games item.
+- Docs: *Built-in commands* regenerated; *Menu guidelines* names a domain submenu **Games** for an emulator and no longer lists Emulator at the top level. `TestHost.otherResolvers` examples use a neutral id (`example.emulator`). `llms.txt` and `llms-full.txt` regenerated.
+
 ## 1.5.27
 
 **Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Plugins pick the fix up with the player's next SDK upgrade (the player builds the `plugin` object with its own copy); nothing in a plugin changes.

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).
@@ -123,7 +199,6 @@ export const BUILTIN_SUBMENUS = Object.freeze([
     },
     { path: ["Settings", "Language"], plugins: ["vestra.preferences"] },
     { path: ["Copy to Clipboard"], plugins: ["vestra.playback"] },
-    { path: ["Emulator"], plugins: ["vestra.nes"] },
 ]);
 /** owner | id | key path, or (title) outside the menu | bindings | panel */
 const BUILTIN_COMMAND_TABLE = `
@@ -228,8 +303,8 @@ vestra.subtitles | second-position-aboveMain | Subtitles ▸ Secondary Subtitle
 vestra.subtitles | bold | Subtitles ▸ Subtitle Style ▸ Bold | Alt+B
 vestra.subtitles | size-up | Subtitles ▸ Subtitle Style ▸ Size + | Alt+PageUp
 vestra.subtitles | size-down | Subtitles ▸ Subtitle Style ▸ Size − | Alt+PageDown
-vestra.subtitles | move-up | Subtitles ▸ Subtitle Style ▸ Move Up | Alt+ArrowUp
-vestra.subtitles | move-down | Subtitles ▸ Subtitle Style ▸ Move Down | Alt+ArrowDown
+vestra.subtitles | move-up | Subtitles ▸ Subtitle Style ▸ Move Up
+vestra.subtitles | move-down | Subtitles ▸ Subtitle Style ▸ Move Down
 vestra.subtitles | move-reset | Subtitles ▸ Subtitle Style ▸ Reset Position | Alt+Home
 vestra.subtitles | shadow | Subtitles ▸ Subtitle Style ▸ Shadow
 vestra.subtitles | box | Subtitles ▸ Subtitle Style ▸ Opaque Box
@@ -369,9 +444,6 @@ vestra.audio | audio.normalize | Audio ▸ Processing ▸ Normalize | Shift+N
 vestra.audio | audio.clarity | Audio ▸ Processing ▸ Crystalizer | Shift+C
 vestra.audio | audio.reset | Audio ▸ Reset
 vestra.visualizer | audio-cover | Audio ▸ Show Album Cover for Audio Only
-vestra.nes | nes.open | Emulator ▸ Open NES ROM…
-vestra.nes | nes.stop | Emulator ▸ Stop NES
-vestra.nes | nes.window | Emulator ▸ NES Tools…
 host | fullscreen | Toggle Fullscreen | Enter, Alt+Enter, F11
 vestra.window | pip | Screen ▸ Picture-in-Picture
 vestra.window | mini | Screen ▸ Mini Size | \`
@@ -417,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
@@ -962,7 +995,7 @@ export declare class TestHost implements Transport {
      * @example
      * ```ts
      * const host = new TestHost();
-     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.otherResolvers.push({ owner: "example.emulator", extensions: ["nes"] });
      * ```
      */
     readonly otherResolvers: {
@@ -989,7 +1022,7 @@ export declare class TestHost implements Transport {
      *
      * @example
      * ```ts
-     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.otherResolvers.push({ owner: "example.emulator", extensions: ["nes"] });
      * host.updateFileTypes();
      * await host.settle();
      * assert.deepEqual(plugin.resolvers.fileTypes, ["nes"]);
@@ -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. */
@@ -1079,7 +1081,7 @@ export class TestHost {
      * @example
      * ```ts
      * const host = new TestHost();
-     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.otherResolvers.push({ owner: "example.emulator", extensions: ["nes"] });
      * ```
      */
     otherResolvers = [];
@@ -1107,7 +1109,7 @@ export class TestHost {
      *
      * @example
      * ```ts
-     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.otherResolvers.push({ owner: "example.emulator", extensions: ["nes"] });
      * host.updateFileTypes();
      * await host.settle();
      * assert.deepEqual(plugin.resolvers.fileTypes, ["nes"]);
@@ -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 ?? [])])