@vestra-player/sdk 1.5.28 → 1.5.30

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.5.30
+
+**Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Only documentation, its checks and the generated `llms-full.txt` change.
+
+- **Every example explains what it does and how it works.** The standard, in *Maintaining* ("Examples in reference comments"): an `@example` has a task title, a lead saying what it does and how it works (checked against the SDK and the player's source), code that compiles on its own with comments on the key lines, and error handling where the user can make a call fail. All 159 examples of the API now meet it (none did before this release), including the 65 of the UI category, the test helpers (`TestHost`, `startPlugin`, `HostError`), the limits and tables (`COMMAND_LIMITS`, `MENU_IDS`, `BUILTIN_*`, `BAR_BUTTON_ICONS`, `CAPABILITY_INFO`, `BINDING_INPUTS`, `OSD_LIMITS`, `SESSION_STORAGE_LIMITS`, `SECRET_LIMITS`, `UI_VALUE_LIMITS`, `THEME_PALETTES`) and the 1.5.29 bar buttons (`CommandButton`, `TestHost.barButtons`). Every example now type checks (61 did not). Examples no longer compose shown sentences in TypeScript: OSD and dialog texts are templates with arguments.
+- **Corrections found on the way.** `Subtitles.setStyle`, `SubtitlesState.style` and `SubtitleStyle`: when several plugins set a style layer, the effective one is the layer of the plugin whose manifest id sorts last, not the latest call. `COMMAND_LIMITS`: `add` never throws `limit`; the player refuses the registration (activation fails, or `Scope.onError`). `startPlugin`'s restart example gives both runs the same `dataDirectory` instead of copying the data before `stop()` (which could miss a pending store write). `TestHost.settle` says the debounced store write is not waited for. `TestHost.dialogAnswers` is one queue for every kind of dialog. `TestHost.openElsewhere`: calls that return nothing (`TimelineLayer.set` with `ifCurrent`) drop the write silently instead of rejecting. Resolver examples (`I18n.error`, `FileResolverOptions`, `TestHost.otherResolvers`) use a made-up `.ch8` format instead of `.nes`, which the store plugin VestraNES owns.
+- **`llms-full.txt` carries the examples and `@remarks`** of every declaration and member (hidden setup lines dropped, `{@includeCode}` inlined), so the plugin workshop's model sees them: 536 KB → 693 KB (about 137k → 177k tokens). `llms.txt` wording trimmed to stay under its 9 KB limit (9,134 bytes).
+- **Hidden setup lines**: in an `@example` code block, lines above `// ---cut---` are type checked but not shown on the site or in `llms-full.txt`.
+- **Checks.** `docs:check` fails on any block that does not compile (it only warned for most examples; `--lenient` keeps the old behaviour for work in progress). `doc-lint` gains `example-lead` (task title, lead, comments, one `// ---cut---` at most; `See` markers for trivial siblings, whose link must resolve, at most 20 % of a declaration's methods) and `stale-refs` (removed or handed-over names such as `vestra.nes`, `.nes` resolvers), enforced for every example and Markdown code block, and prints per category the share of methods with an explained example. `EXAMPLE_BASELINE` keeps known violations per problem when a rule is tightened; it is empty, and `test/doc-baseline.test.ts` keeps it from growing.
+- The parts of `examples/bookmark`, `examples/markdown` and `examples/panel-menu` that the reference includes gained comments on their key lines.
+- Test only: the storage test in `test/round2.test.ts` waits for the debounced file to appear and for `flush()` instead of a fixed 60 ms, and stops its plugins before removing their data directory, so it no longer fails now and then with `ENOENT` on a loaded machine.
+
+## 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/capabilities.d.ts

@@ -49,13 +49,23 @@ export interface CapabilityInfo {
  * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
  * and `plugin.packages.list`).
  *
- * @example
+ * @example Check in a test that the manifest declares every required capability
+ * The test fails, naming the missing capability, when the manifest declares
+ * a capability without one its members also need. It reads the plugin's own
+ * `manifest.json` and looks each declared name up in `CAPABILITY_INFO`,
+ * whose `requires` lists the capabilities that must be declared with it;
+ * at run time the player would refuse such a call with code `capability`.
  * ```ts
+ * import assert from "node:assert/strict";
+ * import { readFile } from "node:fs/promises";
  * import { CAPABILITY_INFO } from "@vestra-player/sdk/testing";
  *
- * const manifest = JSON.parse(await readFile("manifest.json", "utf8"));
+ * const manifest: { capabilities: string[] } = JSON.parse(
+ *   await readFile(new URL("../manifest.json", import.meta.url), "utf8"),
+ * );
  * for (const capability of manifest.capabilities)
- *   for (const needed of CAPABILITY_INFO[capability].requires)
+ *   // An unknown name has no entry: `vestra-plugin check` reports it.
+ *   for (const needed of CAPABILITY_INFO[capability]?.requires ?? [])
  *     assert.ok(manifest.capabilities.includes(needed), needed);
  * ```
  *

package/dist/capabilities.js

@@ -13,13 +13,23 @@ import { capabilityInfo } from "./capability-rules.js";
  * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
  * and `plugin.packages.list`).
  *
- * @example
+ * @example Check in a test that the manifest declares every required capability
+ * The test fails, naming the missing capability, when the manifest declares
+ * a capability without one its members also need. It reads the plugin's own
+ * `manifest.json` and looks each declared name up in `CAPABILITY_INFO`,
+ * whose `requires` lists the capabilities that must be declared with it;
+ * at run time the player would refuse such a call with code `capability`.
  * ```ts
+ * import assert from "node:assert/strict";
+ * import { readFile } from "node:fs/promises";
  * import { CAPABILITY_INFO } from "@vestra-player/sdk/testing";
  *
- * const manifest = JSON.parse(await readFile("manifest.json", "utf8"));
+ * const manifest: { capabilities: string[] } = JSON.parse(
+ *   await readFile(new URL("../manifest.json", import.meta.url), "utf8"),
+ * );
  * for (const capability of manifest.capabilities)
- *   for (const needed of CAPABILITY_INFO[capability].requires)
+ *   // An unknown name has no entry: `vestra-plugin check` reports it.
+ *   for (const needed of CAPABILITY_INFO[capability]?.requires ?? [])
  *     assert.ok(manifest.capabilities.includes(needed), needed);
  * ```
  *

package/dist/commands.d.ts

@@ -1,21 +1,32 @@
 /** 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
  * table (the player's tests check that they agree). They are runaway guards,
- * not product limits: a command added past them fails with code `limit`
- * (its `ready` rejects; during activation, activation fails), commands
+ * not product limits: a command added past them is refused by the player
+ * with code `limit` (its `ready` rejects; during activation, activation
+ * fails; later the failure goes to `Scope.onError`), commands
  * already registered are unaffected, and disposing a command frees its slot
  * at once. {@link TestHost} enforces the same caps.
  *
  * For menus built from media content (tracks, chapters, presets), set your
  * own sensible display cap well below `perPlugin`.
  *
- * @example
+ * @example Cap a chapter menu well below the command limit
+ * The Chapters submenu lists at most 50 chapters, however many the file
+ * has. Every menu item is a command, and the player counts them per plugin.
+ * `add` itself returns at once and never throws `limit`: past `perPlugin`
+ * the player refuses the registration, which fails the activation or, later,
+ * reaches `Scope.onError`. A try/catch around `add` cannot catch that, so a
+ * menu built from media content keeps its own cap and leaves room for the
+ * plugin's fixed commands.
  * ```ts
+ * declare const chapters: { title: string; time: number }[];
+ * // ---cut---
  * import { COMMAND_LIMITS } from "@vestra-player/sdk/testing";
  *
+ * // 20 slots stay free for the plugin's own commands.
  * const shown = chapters.slice(0, Math.min(50, COMMAND_LIMITS.perPlugin - 20));
  * ```
  */
@@ -36,14 +47,65 @@ export declare const COMMAND_LIMITS: {
  * `@video` as a menu of its own. The player's tests check that this list
  * agrees with the player's.
  *
- * @example
+ * @example Put a command into the built-in Video menu
+ * "Blur" appears in the player's Video menu in every interface language.
+ * The player replaces a leading `@video` with that menu's key ("Video")
+ * before it merges paths, so the item joins the built-in menu; an id that
+ * is not in `MENU_IDS` makes `add` fail with `invalid`, which a test can
+ * rule out ahead of time.
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * // ---cut---
+ * import assert from "node:assert/strict";
  * import { MENU_IDS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(MENU_IDS.includes("video"));
+ * plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run() {} });
+ * assert.ok(MENU_IDS.includes("video")); // a menu id, not a title
  * ```
  */
 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 Check in a test that the button's icon exists
+ * The test fails before release if the plugin's bar button names an icon
+ * the player does not have. `commands.add` would refuse an unknown name
+ * with `invalid`; the player's tests keep `BAR_BUTTON_ICONS` equal to its
+ * icon set, so checking against it is the same check without a player.
+ * ```ts
+ * import assert from "node:assert/strict";
+ * import { BAR_BUTTON_ICONS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(BAR_BUTTON_ICONS.includes("store")); // the icon main.ts uses
+ * ```
+ *
+ * @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}.
@@ -71,13 +133,23 @@ export interface BuiltinSubmenu {
  * listed. The player's tests check that this list agrees with what its
  * built-in plugins declare.
  *
- * @example
+ * @example Add an item to the built-in Snapshot submenu
+ * "Copy Snapshot" appears in Video ▸ Snapshot next to the built-in capture
+ * plugin's items. Paths merge by their English keys, so a command whose
+ * path continues with the submenu's keys (`["Video", "Snapshot"]`, the menu
+ * written as `@video`) lands in the same submenu whatever the interface
+ * language.
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare function copySnapshot(): Promise<void>;
+ * // ---cut---
  * import { BUILTIN_SUBMENUS } from "@vestra-player/sdk/testing";
  *
  * const snapshot = BUILTIN_SUBMENUS.find((menu) => menu.path.at(-1) === "Snapshot")!;
  * plugin.commands.add({
  *   id: "snapshot-to-clipboard",
+ *   // ["@video", "Snapshot", "Copy Snapshot"]; @video stands for "Video".
  *   path: ["@video", ...snapshot.path.slice(1), "Copy Snapshot"],
  *   run: copySnapshot,
  * });
@@ -120,7 +192,12 @@ export interface BuiltinCommand {
  * placeholders (`No Audio Tracks`) are. The player's tests check that this
  * list agrees with what the player and its built-in plugins register.
  *
- * @example
+ * @example Check in a test that a default key is still free
+ * The test fails if the player or a built-in plugin already binds Ctrl+K
+ * globally, before users ever see a conflict. It collects the default
+ * bindings of every built-in command that is not limited to its panel's
+ * focus (`focus: null`) and looks for the key the plugin wants; bindings
+ * are canonical, so compare them as the player writes them.
  * ```ts
  * import assert from "node:assert/strict";
  * import { BUILTIN_COMMANDS } from "@vestra-player/sdk/testing";
@@ -157,6 +234,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

@@ -1,18 +1,29 @@
 /**
  * The player's command registry caps, the same values as the player's own
  * table (the player's tests check that they agree). They are runaway guards,
- * not product limits: a command added past them fails with code `limit`
- * (its `ready` rejects; during activation, activation fails), commands
+ * not product limits: a command added past them is refused by the player
+ * with code `limit` (its `ready` rejects; during activation, activation
+ * fails; later the failure goes to `Scope.onError`), commands
  * already registered are unaffected, and disposing a command frees its slot
  * at once. {@link TestHost} enforces the same caps.
  *
  * For menus built from media content (tracks, chapters, presets), set your
  * own sensible display cap well below `perPlugin`.
  *
- * @example
+ * @example Cap a chapter menu well below the command limit
+ * The Chapters submenu lists at most 50 chapters, however many the file
+ * has. Every menu item is a command, and the player counts them per plugin.
+ * `add` itself returns at once and never throws `limit`: past `perPlugin`
+ * the player refuses the registration, which fails the activation or, later,
+ * reaches `Scope.onError`. A try/catch around `add` cannot catch that, so a
+ * menu built from media content keeps its own cap and leaves room for the
+ * plugin's fixed commands.
  * ```ts
+ * declare const chapters: { title: string; time: number }[];
+ * // ---cut---
  * import { COMMAND_LIMITS } from "@vestra-player/sdk/testing";
  *
+ * // 20 slots stay free for the plugin's own commands.
  * const shown = chapters.slice(0, Math.min(50, COMMAND_LIMITS.perPlugin - 20));
  * ```
  */
@@ -33,11 +44,21 @@ export const COMMAND_LIMITS = {
  * `@video` as a menu of its own. The player's tests check that this list
  * agrees with the player's.
  *
- * @example
+ * @example Put a command into the built-in Video menu
+ * "Blur" appears in the player's Video menu in every interface language.
+ * The player replaces a leading `@video` with that menu's key ("Video")
+ * before it merges paths, so the item joins the built-in menu; an id that
+ * is not in `MENU_IDS` makes `add` fail with `invalid`, which a test can
+ * rule out ahead of time.
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * // ---cut---
+ * import assert from "node:assert/strict";
  * import { MENU_IDS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(MENU_IDS.includes("video"));
+ * plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run() {} });
+ * assert.ok(MENU_IDS.includes("video")); // a menu id, not a title
  * ```
  */
 export const MENU_IDS = [
@@ -49,6 +70,86 @@ 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 Check in a test that the button's icon exists
+ * The test fails before release if the plugin's bar button names an icon
+ * the player does not have. `commands.add` would refuse an unknown name
+ * with `invalid`; the player's tests keep `BAR_BUTTON_ICONS` equal to its
+ * icon set, so checking against it is the same check without a player.
+ * ```ts
+ * import assert from "node:assert/strict";
+ * import { BAR_BUTTON_ICONS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(BAR_BUTTON_ICONS.includes("store")); // the icon main.ts uses
+ * ```
+ *
+ * @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).
@@ -59,13 +160,23 @@ export const MENU_IDS = [
  * listed. The player's tests check that this list agrees with what its
  * built-in plugins declare.
  *
- * @example
+ * @example Add an item to the built-in Snapshot submenu
+ * "Copy Snapshot" appears in Video ▸ Snapshot next to the built-in capture
+ * plugin's items. Paths merge by their English keys, so a command whose
+ * path continues with the submenu's keys (`["Video", "Snapshot"]`, the menu
+ * written as `@video`) lands in the same submenu whatever the interface
+ * language.
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare function copySnapshot(): Promise<void>;
+ * // ---cut---
  * import { BUILTIN_SUBMENUS } from "@vestra-player/sdk/testing";
  *
  * const snapshot = BUILTIN_SUBMENUS.find((menu) => menu.path.at(-1) === "Snapshot")!;
  * plugin.commands.add({
  *   id: "snapshot-to-clipboard",
+ *   // ["@video", "Snapshot", "Copy Snapshot"]; @video stands for "Video".
  *   path: ["@video", ...snapshot.path.slice(1), "Copy Snapshot"],
  *   run: copySnapshot,
  * });
@@ -413,6 +524,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
@@ -456,7 +568,12 @@ vestra.playlist | playlist.settings | (Playlist Settings…) | F5 | panel
  * placeholders (`No Audio Tracks`) are. The player's tests check that this
  * list agrees with what the player and its built-in plugins register.
  *
- * @example
+ * @example Check in a test that a default key is still free
+ * The test fails if the player or a built-in plugin already binds Ctrl+K
+ * globally, before users ever see a conflict. It collects the default
+ * bindings of every built-in command that is not limited to its panel's
+ * focus (`focus: null`) and looks for the key the plugin wants; bindings
+ * are canonical, so compare them as the player writes them.
  * ```ts
  * import assert from "node:assert/strict";
  * import { BUILTIN_COMMANDS } from "@vestra-player/sdk/testing";

package/dist/index.d.ts

@@ -12,7 +12,12 @@
  * documents the manifest capability it needs. Errors are described at
  * {@link PluginError}. Tests use `@vestra-player/sdk/testing`.
  *
- * @example
+ * @example Add a menu item that shows a message
+ * The player gets a Tools ▸ Hello menu item; picking it shows "Hello" on
+ * the video. The player imports the entry module and calls `activate` with
+ * the plugin's `Plugin` object; `commands.add` registers the item (manifest
+ * capability `commands`), and the player calls `run` when the user picks it
+ * or presses a key bound to it. `osd.show` needs `ui.osd`.
  * ```ts
  * import type { Plugin } from "@vestra-player/sdk";
  *

package/dist/palettes.d.ts

@@ -11,11 +11,25 @@
  * the palette (`slint/palette.slint`); the player's tests check both
  * palettes against its own.
  *
- * @example
+ * @example Check in a test that a colour stays readable in both themes
+ * The test fails if the plugin's own highlight colour gets too close to
+ * the panel background of either palette. Plugins draw with `Theme` tokens
+ * in Slint and the player switches palettes; a colour the plugin picks
+ * itself does not switch, so a test compares it with each palette's values
+ * (hex strings, `#rrggbb`).
  * ```ts
+ * import assert from "node:assert/strict";
  * import { THEME_PALETTES } from "@vestra-player/sdk/testing";
  *
- * const accent = THEME_PALETTES["vestra-light"].accent; // "#d4128a"
+ * const highlight = "#e07000"; // the plugin's own orange
+ * const luminance = (hex: string) => {
+ *   const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+ *   return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!; // rough, without gamma
+ * };
+ * for (const [name, palette] of Object.entries(THEME_PALETTES)) {
+ *   const gap = Math.abs(luminance(highlight) - luminance(palette["bg-panel"]!));
+ *   assert.ok(gap > 0.3, `${name}: highlight too close to bg-panel`);
+ * }
  * ```
  *
  * @since 1.5.14

package/dist/palettes.js

@@ -11,11 +11,25 @@
  * the palette (`slint/palette.slint`); the player's tests check both
  * palettes against its own.
  *
- * @example
+ * @example Check in a test that a colour stays readable in both themes
+ * The test fails if the plugin's own highlight colour gets too close to
+ * the panel background of either palette. Plugins draw with `Theme` tokens
+ * in Slint and the player switches palettes; a colour the plugin picks
+ * itself does not switch, so a test compares it with each palette's values
+ * (hex strings, `#rrggbb`).
  * ```ts
+ * import assert from "node:assert/strict";
  * import { THEME_PALETTES } from "@vestra-player/sdk/testing";
  *
- * const accent = THEME_PALETTES["vestra-light"].accent; // "#d4128a"
+ * const highlight = "#e07000"; // the plugin's own orange
+ * const luminance = (hex: string) => {
+ *   const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+ *   return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!; // rough, without gamma
+ * };
+ * for (const [name, palette] of Object.entries(THEME_PALETTES)) {
+ *   const gap = Math.abs(luminance(highlight) - luminance(palette["bg-panel"]!));
+ *   assert.ok(gap > 0.3, `${name}: highlight too close to bg-panel`);
+ * }
  * ```
  *
  * @since 1.5.14

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";