@vestra-player/sdk 1.5.39 → 1.5.41

package/dist/wire.d.ts

@@ -376,11 +376,11 @@ export declare function createWire(transport: Transport): {
         operation: (token: import("./processing.ts").ProcessingToken) => Promise<import("./processing.ts").ProcessingOperation>;
     };
     commands: {
-        register: (id: string, revision: number, declaration: import("./commands.ts").CommandDeclaration, state: import("./commands.ts").CommandState) => Promise<{
+        register: (id: string, revision: number, declaration: import("./commands.ts").CommandDeclaration, state: import("./commands.ts").CommandState, when?: import("./commands.ts").CommandWhen) => Promise<{
             revision: number;
         }>;
         unregister: (id: string) => Promise<void>;
-        update: (id: string, revision: number, state: import("./commands.ts").CommandState) => Promise<{
+        update: (id: string, revision: number, state: import("./commands.ts").CommandState, when?: import("./commands.ts").CommandWhen) => Promise<{
             revision: number;
         }>;
     };
@@ -615,14 +615,14 @@ export declare function createWire(transport: Transport): {
          * only the SDK keeps a copy of the state (player 0.5.18; older
          * players ignore it); `listen` changes it.
          */
-        subscribe(event: HostEvent, listener: (data: unknown) => void, mirror?: boolean): Promise<() => Promise<void>>;
+        subscribe(event: HostEvent, listener: (data: unknown) => void, mirror?: boolean, why?: string[]): Promise<() => Promise<void>>;
         /**
          * Tell the player whether a subscribed event has a real listener
          * (`active`) or only the SDK's copy of the state: `events.subscribe`
          * again, which replaces the mark (player 0.5.18; older players keep
          * one subscription per name and ignore the mark).
          */
-        listen: (event: HostEvent, active: boolean) => Promise<void>;
+        listen: (event: HostEvent, active: boolean, why?: string[]) => Promise<void>;
     };
     ui: {
         /** Player 0.2.0: the remote images a Markdown document shows. */

package/dist/wire.js

@@ -265,13 +265,19 @@ export function createWire(transport) {
              * only the SDK keeps a copy of the state (player 0.5.18; older
              * players ignore it); `listen` changes it.
              */
-            async subscribe(event, listener, mirror = false) {
+            async subscribe(event, listener, mirror = false, 
+            /** What listens (player 0.5.21 logs it; older players ignore it). */
+            why) {
                 const off = transport.on(event, listener);
                 let subscription = subscriptions.get(event);
                 if (!subscription) {
                     subscription = {
                         count: 0,
-                        ready: transport.request("events.subscribe", mirror ? { event, mirror: true } : { event }),
+                        ready: transport.request("events.subscribe", mirror
+                            ? { event, mirror: true }
+                            : why?.length
+                                ? { event, why }
+                                : { event }),
                     };
                     subscriptions.set(event, subscription);
                 }
@@ -302,7 +308,11 @@ export function createWire(transport) {
              * again, which replaces the mark (player 0.5.18; older players keep
              * one subscription per name and ignore the mark).
              */
-            listen: (event, active) => transport.request("events.subscribe", active ? { event } : { event, mirror: true }),
+            listen: (event, active, why) => transport.request("events.subscribe", active
+                ? why?.length
+                    ? { event, why }
+                    : { event }
+                : { event, mirror: true }),
         },
         ui: {
             /** Player 0.2.0: the remote images a Markdown document shows. */

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.39: full reference
+# @vestra-player/sdk 1.5.41: 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.
 
@@ -2710,6 +2710,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.13 | SystemInfo.renderingReason, RenderingMode, RenderingPreference, RenderingReasonCode, RenderingReason, RenderingState, Rendering |
 | 0.5.16 | UpscalingReasonCode, UpscalingReason, UpscalingState, VideoUpscaling |
 | 0.5.20 | VideoShaders |
+| 0.5.21 | Scope.when, When, Bindings.onChange |
 
 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).
 
@@ -3329,7 +3330,7 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | `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.
+- **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. The icon is drawn in the accent colour (player 0.5.22; the text colour before), darker while pressed. Disabled or busy: drawn disabled, a click runs nothing. `checked: true`: a small dot in the icon's colour under the icon (before player 0.5.22: the icon in the accent colour, the others in the text 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.
@@ -3897,6 +3898,10 @@ rest of the plugin keeps running.
 interface Scope extends Disposable {
   /** Menu commands and their default bindings (`commands`). */
   readonly commands: Commands;
+  /**
+   * Conditions on the player's own state for a command's `enabled` and `checked` (SDK 1.5.40, player 0.5.21): the player evaluates them, so the menu follows playback even while the plugin is stopped. See When.
+   */
+  readonly when: When;
   /** Tool windows from `.slint` files (`ui.window`). */
   readonly windows: Windows;
   /** Docked panels: bottom bar, sidebar and backdrop (`ui.mount`). */
@@ -4238,6 +4243,191 @@ plugin.commands.add({
 });
 ```
 
+### Condition
+
+A condition on the player's own state, from Scope.when, for a
+command's `enabled` or `checked`. The player evaluates it, again on
+every change of that state, whether or not the plugin runs.
+
+Combine conditions with `and`, `or` and `not`; each returns a new
+condition and leaves the original as it was. A condition is data: it
+reads nothing in the plugin and keeps no listener, so a plugin whose
+menu state is made of conditions may be stopped while idle (lazy
+activation) and its menu stays current. A function (see Bindable)
+keeps working; one that reads `plugin.player.state` or another service's
+state keeps the plugin running so the SDK can evaluate it.
+
+- @capability commands
+
+```ts
+interface Condition {
+  /**
+   * True when this condition and every one of `others` hold.
+   * @capability None (the command it is given to needs `commands`).
+   * @example Combine two conditions with and
+   * The item is enabled only while a file plays in fullscreen. `and`
+   * returns a new condition; `when.playing` itself is unchanged.
+   * ```ts
+   * const { when } = plugin;
+   * const playingFullscreen = when.playing.and(when.fullscreen);
+   * ```
+   */
+  and(...others: Condition[]): Condition;
+  /**
+   * True when this condition or one of `others` holds.
+   * @capability None (the command it is given to needs `commands`).
+   * @example Combine two conditions with or
+   * The item is enabled while a file plays or is paused. `or` returns a
+   * new condition that holds when either of the two holds.
+   * ```ts
+   * const { when } = plugin;
+   * const active = when.playing.or(when.paused);
+   * ```
+   */
+  or(...others: Condition[]): Condition;
+  /**
+   * True when this condition does not hold.
+   * @capability None (the command it is given to needs `commands`).
+   * @example Negate a condition with not
+   * An "Enter Fullscreen" item is enabled only outside fullscreen. `not`
+   * returns the opposite condition; the player evaluates it on every
+   * window change.
+   * ```ts
+   * const { when } = plugin;
+   * const windowed = when.fullscreen.not();
+   * ```
+   */
+  not(): Condition;
+}
+```
+
+Example: Enable an item while a frame can be saved
+
+"Save Snapshot" is greyed out with its reason unless a media file is
+open at a frame the player can capture. The condition is sent with the
+command and evaluated by the player, so the item follows playback even
+while the plugin is stopped; with an `enabled` condition the player
+shows the `reason` only while the item is disabled.
+```ts
+const { when } = plugin;
+plugin.commands.add({
+  id: "save",
+  path: ["@video", "Save Snapshot"],
+  enabled: when.can("snapshot").and(when.phase("ready", "ended"), when.stream.not()),
+  reason: "No frame to capture", // shown only while disabled
+  run: saveSnapshot,
+});
+```
+
+### When
+
+`plugin.when`: the vocabulary of conditions (SDK 1.5.40, player 0.5.21).
+It names only state the player owns: the source's phase, kind, pause
+and controls (the same names as PlayerState), fullscreen, the
+palette and the saved interface language.
+
+Give a condition as a command's `enabled` or `checked`
+(CommandOptions, Command.set). The player evaluates it
+and shows the result in menus, on keys and on bar buttons, again
+whenever that state changes, also while the plugin is stopped because
+nothing used it. With an `enabled` condition the player shows the
+command's `reason` only while the condition is false (or the command
+is busy), so a fixed reason is enough. Players before 0.5.21 have no
+`plugin.when` (declare `"minPlayerVersion": "0.5.21"`).
+
+State the vocabulary does not name (a plugin's own settings, an open
+window, a track list) stays a function or a value set with
+Command.set.
+
+- @capability commands
+
+```ts
+interface When {
+  /** A source is open: any phase but `empty` (loading, ready, ended, error). */
+  readonly open: Condition;
+  /** The source is loaded and can play (`phase` is `ready`). */
+  readonly ready: Condition;
+  /** The source is ready and not paused. */
+  readonly playing: Condition;
+  /** The source is ready and paused. */
+  readonly paused: Condition;
+  /** The source is a generated stream (`PlayerState.kind` is `stream`). */
+  readonly stream: Condition;
+  /** The main window is fullscreen. */
+  readonly fullscreen: Condition;
+  /**
+   * The source's `phase` is one of `phases`.
+   * @throws TypeError (throws) No phase, or one that is not a phase.
+   * @capability None (the command it is given to needs `commands`).
+   * @example Enable an item while a file is loaded or finished
+   * The item is enabled while the source is ready or has ended, as a
+   * snapshot needs a frame. The phases are those of `PlayerState.phase`.
+   * ```ts
+   * const { when } = plugin;
+   * const hasFrame = when.phase("ready", "ended");
+   * ```
+   */
+  phase(...phases: PlayerState["phase"][]): Condition;
+  /**
+   * The source allows `control`: `PlayerState.can[control]` is true.
+   * @throws TypeError (throws) `control` is not one of `PlayerState.can`.
+   * @capability None (the command it is given to needs `commands`).
+   * @example Enable a seek item only where seeking works
+   * "Jump to Middle" is greyed out on live streams that cannot seek.
+   * The player reads its own `can.seek` for the current source.
+   * ```ts
+   * const { when } = plugin;
+   * const seekable = when.can("seek");
+   * ```
+   */
+  can(control: keyof PlayerState["can"]): Condition;
+  /**
+   * The palette in use is `theme` (`plugin.appearance.theme`).
+   * @throws TypeError (throws) `theme` is not a palette of the player.
+   * @capability None (the command it is given to needs `commands`).
+   * @example Check the light palette's item
+   * The item carries a check mark while the light palette is in use,
+   * whoever switched to it.
+   * ```ts
+   * const { when } = plugin;
+   * const light = when.theme("vestra-light");
+   * ```
+   */
+  theme(theme: ThemeId): Condition;
+  /**
+   * The saved interface language is `language` (`plugin.appearance.language`: `"system"` or a locale).
+   * @throws TypeError (throws) `language` is not `"system"` or a locale.
+   * @capability None (the command it is given to needs `commands`).
+   * @example Check the Follow System item
+   * The item carries a check mark while the player follows the system's
+   * language; the player reads its own saved preference.
+   * ```ts
+   * const { when } = plugin;
+   * const followSystem = when.language("system");
+   * ```
+   */
+  language(language: LanguagePreference): Condition;
+}
+```
+
+Example: Check a palette item and follow the palette
+
+The Appearance submenu has one radio item per palette; the player
+checks the one in use, also after another plugin or the user changed
+it, and while this plugin is stopped. Nothing in the plugin listens to
+the palette.
+```ts
+const { when } = plugin;
+for (const [id, title] of [["vestra", "Dark"], ["vestra-light", "Light"]] as const)
+  plugin.commands.add({
+    id: `theme.${id}`,
+    path: ["Settings", "Appearance", title],
+    radio: true,
+    checked: when.theme(id), // evaluated by the player, not the plugin
+    run: () => plugin.appearance.set(id),
+  });
+```
+
 ### MenuId
 
 A built-in top-level menu of the player, named in a command path as
@@ -4279,9 +4469,9 @@ Writing a bottom bar.
 "…" 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.
+a click runs nothing. Every button's icon is drawn in the accent colour;
+a command with `checked` shows a small dot under its icon 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
@@ -4439,13 +4629,15 @@ interface CommandOptions {
    * 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. */
-  checked?: Bindable<boolean | null>;
+  /** Whether the command can run (default true): a value, a function, or a Condition the player evaluates (`plugin.when`, SDK 1.5.40). */
+  enabled?: Bindable<boolean> | Condition;
+  /** Check mark (or radio dot with `radio`); `null` (default) draws none. A Condition (`plugin.when`, SDK 1.5.40) draws the mark while it holds. */
+  checked?: Bindable<boolean | null> | Condition;
   /** Busy state (default false); the player does not call `run` while busy. */
   busy?: Bindable<boolean>;
-  /** Why the command is disabled or busy (shown to the user): English source text, or a Text for one with data in it (SDK 1.5.11). */
+  /**
+   * Why the command is disabled or busy (shown to the user): English source text, or a Text for one with data in it (SDK 1.5.11). With an `enabled` Condition the player shows it only while the condition is false or the command is busy, so a fixed text is enough.
+   */
   reason?: Bindable<TextValue | null>;
   /**
    * Run the command (menu item, binding, panel menu or `host.command(id).run()` in tests). It may return a promise; errors and rejections go to Scope.onError, and bound values are re-evaluated when it returns and when its promise settles.
@@ -4497,7 +4689,10 @@ interface Command extends Disposable {
    * ```
    */
   set(state: Partial<{
-    [K in keyof CommandState]: Bindable<CommandState[K]>;
+    [K in "busy" | "reason"]: Bindable<CommandState[K]>;
+  } & {
+    enabled: Bindable<boolean> | Condition;
+    checked: Bindable<boolean | null> | Condition;
   }>): void;
   /**
    * Resolves when the host has registered the command. Rejects with `conflict` (path already taken), `invalid` or `limit` (more than 160 commands in this plugin, or 1024 in the whole player). You rarely need to await it: during activation a failure fails activation, later it goes to Scope.onError.
@@ -11242,12 +11437,13 @@ interface Bindings {
    */
   reset(ref?: BindingRef): Promise<void>;
   /**
-   * Declarations or overrides changed (read `list()` again). At most every 200 ms.
+   * The binding list changed (read `list()` again): a declaration or an override. At most every 200 ms; since player 0.5.21 only when the list itself changed, not when a plugin starts again with the same commands.
    * @capability bindings.manage
    * @example Refresh a key list when bindings change
    * The plugin's key list stays current when the user changes a key in the
-   * player or another plugin starts. The listener carries no data and runs
-   * at most every 200 ms; the plugin reads the table again with `list`.
+   * player or a plugin with other commands is installed. The listener
+   * carries no data and runs at most every 200 ms; the plugin reads the
+   * table again with `list`.
    * ```ts
    * plugin.bindings.onChange(async () => {
    *   const { commands } = await plugin.bindings.list(); // read the new table
@@ -12793,7 +12989,18 @@ interface FakeCommand {
      */
     reason?: string | null;
   };
-  /** The command state the player last received (after the update pass). */
+  /**
+   * The conditions the plugin sent for `enabled` and `checked` (`plugin.when`, wire form), `undefined` without. Like the player, the host evaluates them in FakeCommand.state against `source`, `mainWindow.fullscreen`, `appearance` and `language`.
+   */
+  when?: {
+    /** The condition of `enabled`. */
+    enabled?: Json;
+    /** The condition of `checked`. */
+    checked?: Json;
+  };
+  /**
+   * The command state as the player shows it: what the plugin last sent (after the update pass), with the fields given as conditions (`plugin.when`) evaluated now. With an `enabled` condition, `reason` is `null` while the command is enabled and not busy.
+   */
   state: {
     /** `false` when the plugin disabled the command. */
     enabled: boolean;
@@ -12861,7 +13068,7 @@ interface FakeBarButton {
   readonly order: number;
   /** Clickable: the command is enabled and not busy. */
   readonly enabled: boolean;
-  /** Drawn in the accent colour: the command is checked. */
+  /** Shown with the on dot under its icon: 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;
@@ -13013,6 +13220,10 @@ class TestHost implements Transport {
    * The subscribed events the plugin really listens to: an `onChange` and the like, or a binding that reads the state. The SDK's own copies of the state (what keeps `plugin.player.state` current) are left out. Empty means the player may stop the plugin while nothing uses it (unless it holds something else: a window, a panel, a filter…).
    */
   readonly listening: Set<string>;
+  /**
+   * Why the plugin listens to each event of TestHost.listening: every listener and every binding that reads its state, as the player's log says them (`a listener added at main.ts:12`, `command "Save" enabled is a function that reads plugin.player.state (main.ts:40) — use plugin.when`), in the order they came.
+   */
+  readonly listeningWhy: Map<string, string[]>;
   /**
    * The player's source facts (phase, position, duration, paused, rate, audio tracks, loop, ...). Wire-level shape; change it with TestHost.setSource, which also broadcasts it.
    */
@@ -14493,6 +14704,20 @@ class TestHost implements Transport {
    * ```
    */
   close(): void;
+  /**
+   * Why the player would keep this plugin running while nothing uses it (lazy activation, player 0.5.21), one line per reason, as the player's log says it: an event it listens to that is not one the player wakes it for (with what listens and where it was added), its mounted panel, its open windows. Empty: the player may stop it while idle and start it again on its next use. Filter chains, streams, jobs and the like (which also keep a plugin running) are not listed.
+   * @capability None.
+   * @example Check that a plugin can be stopped while idle
+   * The test fails if the plugin keeps running for no reason after it
+   * starts, and names the reason (a command whose `enabled` reads
+   * `plugin.player.state`, say: give it a `plugin.when` condition). The
+   * player stops such a plugin while nothing uses it and starts it again
+   * on its next use, so it costs no process meanwhile.
+   * ```ts
+   * assert.deepEqual(host.keepsRunning, []);
+   * ```
+   */
+  get keepsRunning(): string[];
 }
 ```
 

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.39: 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>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
+> @vestra-player/sdk 1.5.41: 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>: a line of llms-full.txt (next to this file), which has 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: L2646–2717.
+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: L2646–2718.
 
 **main.ts**
 
@@ -78,9 +78,9 @@ export default async function activate(plugin: Plugin) {
 - `secrets`: Secrets.get/set/delete
 - `rendering.manage`: Rendering.setPreference/restartPlayer
 - `video.upscaling`: VideoUpscaling.state/set
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2718–2778.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2719–2779.
 
-**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` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L2087–2275; TestHost: L12957.
+**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` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L2087–2275; TestHost: L13164.
 
 **Command line**
 
@@ -108,7 +108,7 @@ 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
-- Others: PluginError, llms-full.txt L3797.
+- Others: PluginError, llms-full.txt L3798.
 
 ## Reference
 
@@ -117,30 +117,30 @@ export default async function activate(plugin: Plugin) {
 - Concepts: How a plugin runs L238–418; Commands, menus and key bindings L419–530; Playback state, controls and sources L531–676; Video and audio processing L677–763; Windows, panels, settings pages, dialogs and the OSD L764–1052
 - How-to: Control playback L1053–1181; Store a plugin's data L1182–1249; Load subtitles from a plugin L1250–1328; Keep a slider responsive while dragging L1329–1503; Remember a window's state between runs L1504–1633; Offer a GPU rendering switch L1634–1754; Translate a plugin L1755–1938; Migrate a plugin to English source text L1939–2086; Test a plugin L2087–2275; Publish a plugin L2276–2364; Migrating off package rollback (1.5.16, removed in 1.5.17) L2365–2440
 - Guidelines: Interface guidelines L2441–2548; Menu guidelines L2549–2645
-- Reference: Manifest L2646–2717; Capabilities L2718–2778; Limits L2779–2924; Commands, menus and bindings L2925–3408; Platforms L3409–3439; Theme L3440–3661; Command line L3662–3719
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3720–12641
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12642–15437
+- Reference: Manifest L2646–2718; Capabilities L2719–2779; Limits L2780–2925; Commands, menus and bindings L2926–3409; Platforms L3410–3440; Theme L3441–3662; Command line L3663–3720
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3721–12837
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12838–15662
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L4132, Scope L3872, PluginError L3797, Disposable L3735
-- Commands L4529; Windows L5466; Panels L6912; Dialogs L7582; Player L8323; video: VideoFilter L9203, VideoView L9303, RenderOptions L9390, VideoShaders L9468, VideoUpscaling L9714; audio: AudioFilter L9248; Subtitles L9910; media: MediaCapture L10314; Resolvers L10544; Packages L10946; Osd L9068; Host L8910; Clipboard L11274; Power L11361; Tools L11420; Storage L11572; System L11771; Secrets L11851; window: MainWindow L7229; App L7409; Rendering L12114; Bindings L11174; Ui L4818; Timeline L7141; Drops L6159; Appearance L6240; I18n L6473; Settings L6756.
+- Plugin L4137, Scope L3873, PluginError L3798, Disposable L3736
+- Commands L4724; When L4322; Windows L5661; Panels L7107; Dialogs L7777; Player L8518; video: VideoFilter L9398, VideoView L9498, RenderOptions L9585, VideoShaders L9663, VideoUpscaling L9909; audio: AudioFilter L9443; Subtitles L10105; media: MediaCapture L10509; Resolvers L10739; Packages L11141; Osd L9263; Host L9105; Clipboard L11470; Power L11557; Tools L11616; Storage L11768; System L11967; Secrets L12047; window: MainWindow L7424; App L7604; Rendering L12310; Bindings L11369; Ui L5013; Timeline L7336; Drops L6354; Appearance L6435; I18n L6668; Settings L6951.
 
 ## 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. L15872–15961
-- blur: A tool window with one slider that blurs the playing video. L15962–16223
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L16224–16556
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L16557–16743
-- panel-menu: A sidebar panel with its own right-click menu. L16744–16952
-- menus: Radio menu items, separator groups and a menu item whose title changes. L16953–17112
-- theme-widgets: A tool window drawn with the player's theme and widgets. L17113–17276
-- markdown: A window that shows a Markdown document. L17277–17473
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L17474–17641
+- hello: The README Quick start: one menu command and an on-screen message. L16097–16186
+- blur: A tool window with one slider that blurs the playing video. L16187–16448
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L16449–16781
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L16782–16968
+- panel-menu: A sidebar panel with its own right-click menu. L16969–17177
+- menus: Radio menu items, separator groups and a menu item whose title changes. L17178–17337
+- theme-widgets: A tool window drawn with the player's theme and widgets. L17338–17501
+- markdown: A window that shows a Markdown document. L17502–17698
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L17699–17866
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.39",
+  "version": "1.5.41",
   "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

@@ -12,9 +12,13 @@
 // 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.
+// and press, the bar's tooltip (ToolTipArea). Every enabled cell draws its
+// icon in the accent (accent-press while pressed; icon-disabled when
+// disabled), so the strip reads as one group. A toggle that is on shows a
+// small dot in the icon's colour centred under the icon, like a running app
+// in the macOS Dock (player 0.5.22, SDK 1.5.41; before, icons were in the
+// text colour and only an on toggle in the accent). 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";
@@ -32,7 +36,7 @@ export struct BarButtonItem {
     // 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.
+    // The command has a checked state; `checked` shows the dot under the icon.
     checkable: bool,
     checked: bool,
     // At half opacity: on, but not shown for want of room (the sidebar).
@@ -58,8 +62,11 @@ component Cell inherits Rectangle {
     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;
+        : touch.pressed ? Theme.accent-press : Theme.accent;
+    // The on dot: its diameter and top edge, between the icon box (y 14–26)
+    // and the hover plate's lower edge (y 36).
+    private property <length> dot-size: 4px;
+    private property <length> dot-y: 29px;
     width: 41px;
     height: 40px;
     visible: root.shown;
@@ -99,6 +106,16 @@ component Cell inherits Rectangle {
         image-fit: contain;
         colorize: root.tint;
     }
+    // On (`checked`): the dot under the icon, in the icon's colour.
+    Rectangle {
+        visible: root.item.checked;
+        x: (root.width - 1px - self.width) / 2;
+        y: root.dot-y;
+        width: root.dot-size;
+        height: root.dot-size;
+        border-radius: self.width / 2;
+        background: root.tint;
+    }
     ToolTipArea {
         width: 100%;
         height: 100%;