@vestra-player/sdk 1.6.5 → 1.6.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.6.7
+
+**Who must change: nobody.** The 1.6.6 release below, published again under a new number: its npm publish failed (the provenance transparency log returned 500, then 409 for the same tarball), so 1.6.6 never reached npm. Nothing else changed.
+
+## 1.6.6
+
+**Who must change: nobody.** Additions only: two members of `plugin.commands`, a wire method and event, two Slint widget additions and a `TestHost` method. `apiVersion` stays `vestra/1`, no new capability (`commands` covers them). A plugin that does not use them sends exactly what it sent before. One that uses them needs player 0.7.6 (`"minPlayerVersion": "0.7.6"`): the player builds `plugin` from its own SDK, so on older players `plugin.commands.keys` does not exist (a `TypeError`), and their `@vestra/widgets.slint` has no `KeyHint` or `ToolTipKey`, so a Slint file that uses them does not compile.
+
+- **`plugin.commands.keys(id)`** (player 0.7.6): the keys of one of the plugin's **own** commands, as the player's menus and command palette write them (`["W"]`, `["Ctrl+B"]`, `["⌘B"]` on macOS, arrows as `←`), always the current binding: the user's keys after a change, `[]` when the user cleared them or turned on Ignore Default Shortcuts, `[]` for a key another command holds; mouse bindings and (outside macOS) `Cmd` bindings left out. Read-only and synchronous; read in a `bind` function, the view follows every change. Another plugin's commands, or an unknown id, read `[]`; it needs `commands` only, not `bindings.manage`. The first read asks the player (`commands.keys`) and subscribes to the `commands.keys` event, which the player sends only to the plugin whose own labels changed, at most every 200 ms; until the first answer every command reads `[]`. See [Key hints beside controls](docs/explanation/commands.md#key-hints-beside-controls).
+- **`plugin.commands.onKeysChange(listener)`** (player 0.7.6): runs after any of the plugin's keys changed. `commands.keys` is a wake event, like `bindings.changed`: a listener (or a binding that reads `keys`) does not keep a plugin running while idle, and a plugin in standby is started for a change of its keys.
+- **`KeyHint`** in `@vestra/widgets.slint`: a key cap (monospace `font-xs`, `text-dim`, a 1px border, both palettes); an empty `text` draws nothing and takes no space.
+- **`ToolTipArea.keys`** (a list of the new struct `ToolTipKey`, `{ key, text }`) and **`ToolTipArea.detail`**: the tip reads "Brightness  [W] −  [E] +  · double-click: Default" with key caps. Without them the tip is the plain text tip as before.
+- **`TestHost.rebind(command, inputs | null)`** changes or clears a key of the plugin's command as the user does; `TestHost` answers `commands.keys` and pushes the event like the player, writing labels for `host.systemInfo.os` (macOS by default: `⇧W`, `⌘B`). `bindings.set` and `bindings.reset` push it too.
+- The [theme-widgets example](examples/theme-widgets) shows a slider's two commands (F7, F8) as key caps and in its tooltip.
+
 ## 1.6.5
 
 **Who must change: nobody, but run `vestra-plugin i18n extract` again if a command sets a `category`.** A fix in the plugin CLI only: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability, no player version needed. A plugin whose commands set `category` as a string literal that is not already a message now has those texts in `locales/messages.pot`, so its next `vestra-plugin i18n check` fails with "messages.pot is out of date" until `i18n extract` runs. A category written with `plugin.i18n.text(…)` was already extracted, and a plugin that sets no category sees no change.

package/dist/api-requests.js

@@ -98,6 +98,8 @@ export const API_REQUESTS = Object.freeze({
     "Resolvers.add": [{ method: "sourceResolvers.register" }],
     "Resolvers.onFileTypesChange": [listen("resolvers.fileTypes")],
     "Commands.add": [{ method: "commands.register" }],
+    "Commands.keys": [{ method: "commands.keys" }, listen("commands.keys")],
+    "Commands.onKeysChange": [listen("commands.keys")],
     "Host.run": [{ method: "host.run" }],
     "Windows.create": [{ method: "ui.open" }],
     "Dialogs.confirm": [{ method: "dialogs.confirm" }],

package/dist/commands.d.ts

@@ -345,12 +345,28 @@ export type CommandDeclaration = {
      */
     home?: string;
 };
+/**
+ * `commands.keys` (player 0.7.6): each of the plugin's own commands, by
+ * local id, with the labels of its current keys; the answer to the request
+ * and the data of the event of that name.
+ */
+export type CommandKeys = {
+    keys: Record<string, string[]>;
+    /** The player's binding table revision: a larger one is newer. */
+    revision: number;
+};
 export declare function commandClient(transport: Transport): {
     register: (id: string, revision: number, declaration: CommandDeclaration, state: CommandState, when?: CommandWhen) => Promise<{
         revision: number;
     }>;
     /** Remove the command from the menu and the binding table; the id is free again. */
     unregister: (id: string) => Promise<void>;
+    /**
+     * The key labels of the plugin's own commands, as menus show them
+     * (player 0.7.6); later changes come as the `commands.keys` event, in
+     * the same shape. `revision` orders answers and events.
+     */
+    keys: () => Promise<CommandKeys>;
     update: (id: string, revision: number, state: CommandState, when?: CommandWhen) => Promise<{
         revision: number;
     }>;

package/dist/commands.js

@@ -692,6 +692,12 @@ export function commandClient(transport) {
         }),
         /** Remove the command from the menu and the binding table; the id is free again. */
         unregister: (id) => transport.request("commands.unregister", { id }),
+        /**
+         * The key labels of the plugin's own commands, as menus show them
+         * (player 0.7.6); later changes come as the `commands.keys` event, in
+         * the same shape. `revision` orders answers and events.
+         */
+        keys: () => transport.request("commands.keys", {}),
         update: (id, revision, state, when) => transport.request("commands.update", {
             id,
             revision,

package/dist/host-capabilities.js

@@ -84,6 +84,7 @@ export const HOST_CAPABILITIES = {
                     needs: {
                         cases: {
                             "bindings.changed": "bindings.manage",
+                            "commands.keys": "commands",
                             "packages.changed": null,
                             "video.upscaling.changed": "video.upscaling",
                         },
@@ -96,6 +97,7 @@ export const HOST_CAPABILITIES = {
                     needs: {
                         cases: {
                             "bindings.changed": "bindings.manage",
+                            "commands.keys": "commands",
                             "packages.changed": null,
                             "video.upscaling.changed": "video.upscaling",
                         },
@@ -116,6 +118,7 @@ export const HOST_CAPABILITIES = {
                 { name: "commands.update", needs: "commands" },
                 { name: "commands.unregister", needs: "commands" },
                 { name: "host.run", needs: "commands" },
+                { name: "commands.keys", needs: "commands" },
             ],
             name: "commands",
             requires: [],

package/dist/plugin/bindings.d.ts

@@ -79,3 +79,12 @@ export declare function canonical(text: string): string;
 export declare function checkBindings(bindings: readonly string[]): string[];
 /** `plugin.bindings` (`bindings.manage`): the table and the user overlay. */
 export declare const bindingsApi: (scope: ScopeImpl) => Bindings;
+/**
+ * How the player's menus write a canonical binding (`bindings.rs`
+ * `label_in`), for `TestHost`'s `commands.keys`: `Ctrl+O` and arrows as
+ * ← → ↑ ↓ (`Esc`, `PgUp`, `Num5`); on macOS (`mac`) symbols in Apple's
+ * order ⌃⌥⇧⌘, a `Ctrl` binding as ⌘ (it answers to ⌘ there) and ⌃ only
+ * next to ⌘. `null` for a binding menus do not show: a mouse binding, and
+ * a `Cmd` one outside macOS.
+ */
+export declare function keyLabel(binding: string, mac: boolean): string | null;

package/dist/plugin/bindings.js

@@ -219,3 +219,44 @@ export const bindingsApi = (scope) => ({
         });
     },
 });
+/** Named keys whose label is not their name (the player's `label_in`). */
+const NAMED_LABELS = {
+    ArrowLeft: "←",
+    ArrowRight: "→",
+    ArrowUp: "↑",
+    ArrowDown: "↓",
+    Escape: "Esc",
+    PageUp: "PgUp",
+    PageDown: "PgDn",
+    Delete: "Del",
+    Plus: "+",
+    NumpadPlus: "Num+",
+    NumpadMinus: "Num-",
+    NumpadMultiply: "Num*",
+    NumpadDivide: "Num/",
+    NumpadEnter: "NumEnter",
+    NumpadDecimal: "Num.",
+};
+/**
+ * How the player's menus write a canonical binding (`bindings.rs`
+ * `label_in`), for `TestHost`'s `commands.keys`: `Ctrl+O` and arrows as
+ * ← → ↑ ↓ (`Esc`, `PgUp`, `Num5`); on macOS (`mac`) symbols in Apple's
+ * order ⌃⌥⇧⌘, a `Ctrl` binding as ⌘ (it answers to ⌘ there) and ⌃ only
+ * next to ⌘. `null` for a binding menus do not show: a mouse binding, and
+ * a `Cmd` one outside macOS.
+ */
+export function keyLabel(binding, mac) {
+    if (binding.startsWith("Mouse:"))
+        return null;
+    const parts = binding.split("+");
+    const input = parts.pop();
+    const has = (mod) => parts.includes(mod);
+    const [ctrl, alt, shift, cmd] = ["Ctrl", "Alt", "Shift", "Cmd"].map(has);
+    if (cmd && !mac)
+        return null;
+    const mods = mac
+        ? `${ctrl && cmd ? "⌃" : ""}${alt ? "⌥" : ""}${shift ? "⇧" : ""}${ctrl || cmd ? "⌘" : ""}`
+        : parts.map((mod) => `${mod}+`).join("");
+    const digit = /^Numpad(\d)$/.exec(input)?.[1];
+    return mods + (NAMED_LABELS[input] ?? (digit ? `Num${digit}` : input));
+}

package/dist/plugin/commands.js

@@ -242,6 +242,105 @@ class CommandHandle {
             pending.delete(this.id);
     }
 }
+const NONE = Object.freeze([]);
+const KEYS = "commands.keys";
+/**
+ * One per plugin: the SDK's copy of the key labels of the plugin's own
+ * commands (player 0.7.6). Started by the first `keys` read or
+ * `onKeysChange`: it subscribes to `commands.keys` (a mirror, unless a
+ * listener or a binding holds it), then asks once; the player pushes every
+ * later change. Answers and events carry the binding table's revision, and
+ * an older one than what the copy has is dropped.
+ */
+class KeysService {
+    #runtime;
+    #keys = new Map();
+    #revision = -1;
+    #started = false;
+    #listeners = new Set();
+    constructor(runtime) {
+        this.#runtime = runtime;
+    }
+    start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        const runtime = this.#runtime;
+        // Without `commands` the plugin has no commands: every read is [].
+        if (!runtime.can("commands"))
+            return;
+        runtime.on(KEYS, (data) => this.#accept(data), "commands", true);
+        // Subscribed first: a change after this answer comes as an event.
+        runtime.host.commands.keys().then((answer) => this.#accept(answer), 
+        // An older player (`unsupported`): no keys, as without a binding.
+        () => { });
+    }
+    #accept(data) {
+        const answer = data;
+        const revision = answer?.revision;
+        const keys = answer?.keys;
+        if (typeof revision !== "number" || !keys || typeof keys !== "object")
+            return;
+        if (revision < this.#revision)
+            return;
+        this.#revision = revision;
+        const next = new Map();
+        for (const [id, labels] of Object.entries(keys))
+            if (Array.isArray(labels) && labels.length)
+                next.set(id, Object.freeze(labels.map(String)));
+        const changed = [];
+        for (const id of new Set([...this.#keys.keys(), ...next.keys()])) {
+            const before = this.#keys.get(id) ?? NONE;
+            const after = next.get(id) ?? NONE;
+            if (before.length !== after.length ||
+                before.some((label, at) => label !== after[at]))
+                changed.push(id);
+            // The same labels keep the same array.
+            else if (after !== NONE)
+                next.set(id, before);
+        }
+        this.#keys = next;
+        if (!changed.length)
+            return;
+        this.#runtime.changed(KEYS, changed);
+        for (const listener of [...this.#listeners])
+            listener();
+    }
+    get(id) {
+        return this.#keys.get(id) ?? NONE;
+    }
+    watch(listener) {
+        this.#listeners.add(listener);
+        const held = this.#runtime.hold(KEYS);
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
+    }
+}
+const keysOf = (runtime) => runtime.service("commands.keys", () => new KeysService(runtime));
 export const commands = (scope) => ({
     add: (options) => new CommandHandle(scope, options),
+    keys(id) {
+        if (typeof id !== "string")
+            throw failure("invalid", "keys takes a command id of this plugin");
+        const service = keysOf(scope.runtime);
+        service.start();
+        scope.runtime.reading(KEYS);
+        scope.runtime.depends(KEYS, id);
+        return service.get(id);
+    },
+    onKeysChange(listener) {
+        const service = keysOf(scope.runtime);
+        service.start();
+        const watch = service.watch(() => scope.run(listener));
+        return scope.add({
+            dispose: async () => {
+                scope.forget(watch);
+                await watch.dispose();
+            },
+        });
+    },
 });

package/dist/plugin/runtime.js

@@ -13,6 +13,8 @@ const SDK_DIRECTORY = fileURLToPath(new URL("..", import.meta.url));
 export const WAKE_EVENTS = [
     "packages.changed",
     "bindings.changed",
+    // Player 0.7.6: sent only to the plugin whose own keys changed.
+    "commands.keys",
     "appearance.changed",
     "resolvers.fileTypes",
 ];
@@ -25,6 +27,7 @@ const STATE = {
     "window.state": { name: "plugin.window.state", when: true },
     "appearance.changed": { name: "plugin.appearance", when: true },
     "timeline.changed": { name: "plugin.timeline.marks", when: false },
+    "commands.keys": { name: "plugin.commands.keys", when: false },
     "playback.backend": { name: "plugin.subtitles.state", when: false },
     "resolvers.fileTypes": {
         name: "plugin.resolvers.fileTypes",

package/dist/plugin/testing.d.ts

@@ -2403,6 +2403,34 @@ export declare class TestHost implements Transport {
      * ```
      */
     get conflicts(): string[][];
+    /**
+     * Change the keys of one of the plugin's commands as the user does in
+     * Keyboard Shortcuts (SDK 1.6.6): `inputs` replaces its keys (`[]`
+     * clears them, as Ignore Default Shortcuts does for every default),
+     * `null` gives it its own defaults back. It writes
+     * {@link TestHost.bindings | bindings.overlay}, and the plugin hears it
+     * as from the player: `bindings.changed` and, when what
+     * `plugin.commands.keys` reads changed, `commands.keys`.
+     *
+     * @example Check that a key hint follows a rebinding
+     * The view showed W for Brightness −; after the user moves it to
+     * Shift+W, it shows the new key. `rebind` changes the overlay and
+     * pushes the new labels, and `settle` lets the binding run again. The
+     * test host is a Mac unless `systemInfo.os` says otherwise, hence ⇧W.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.rebind("brightness.down", ["Shift+W"]);
+     * await host.settle();
+     * assert.equal(host.window("picture").props["brightness-down"], "⇧W");
+     * ```
+     *
+     * @capability None.
+     * @throws `Error` `command` is not a command of the plugin.
+     * @since 1.6.6
+     */
+    rebind(command: string, inputs: readonly string[] | null): void;
     /**
      * The binding overlay `plugin.bindings.set` writes (`"<plugin>/<command>"`
      * to inputs; preset it to simulate saved overrides). `press` honours it.

package/dist/plugin/testing.js

@@ -78,7 +78,7 @@ import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
 import { OSD_LIMITS } from "./osd.js";
 import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.js";
 import { SUBTITLE_LIMITS } from "./subtitles.js";
-import { BINDING_INPUTS, canonical } from "./bindings.js";
+import { BINDING_INPUTS, canonical, keyLabel } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
 import { validStep } from "./player.js";
@@ -3080,7 +3080,7 @@ export class TestHost {
             const scope = declaration.focus ? "panel" : "global";
             // The user overlay (`bindings.set`) replaces a command's own bindings.
             const overridden = this.bindings.overlay.get(this.#bindingKey(id));
-            for (const binding of overridden ?? declaration.bindings) {
+            for (const binding of overridden ?? declaration.bindings ?? []) {
                 const key = `${scope} ${binding}`;
                 claims.set(key, [...(claims.get(key) ?? []), id]);
             }
@@ -3091,6 +3091,87 @@ export class TestHost {
     #bindingKey(id) {
         return this.coreCommands.has(id) ? id : `${this.manifestId}/${id}`;
     }
+    /**
+     * Change the keys of one of the plugin's commands as the user does in
+     * Keyboard Shortcuts (SDK 1.6.6): `inputs` replaces its keys (`[]`
+     * clears them, as Ignore Default Shortcuts does for every default),
+     * `null` gives it its own defaults back. It writes
+     * {@link TestHost.bindings | bindings.overlay}, and the plugin hears it
+     * as from the player: `bindings.changed` and, when what
+     * `plugin.commands.keys` reads changed, `commands.keys`.
+     *
+     * @example Check that a key hint follows a rebinding
+     * The view showed W for Brightness −; after the user moves it to
+     * Shift+W, it shows the new key. `rebind` changes the overlay and
+     * pushes the new labels, and `settle` lets the binding run again. The
+     * test host is a Mac unless `systemInfo.os` says otherwise, hence ⇧W.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.rebind("brightness.down", ["Shift+W"]);
+     * await host.settle();
+     * assert.equal(host.window("picture").props["brightness-down"], "⇧W");
+     * ```
+     *
+     * @capability None.
+     * @throws `Error` `command` is not a command of the plugin.
+     * @since 1.6.6
+     */
+    rebind(command, inputs) {
+        if (!this.commands.has(command))
+            throw new Error(`test host: no command ${command}`);
+        const key = this.#bindingKey(command);
+        if (inputs === null)
+            this.bindings.overlay.delete(key);
+        else
+            this.bindings.overlay.set(key, inputs.map(canonical));
+        this.emit("bindings.changed", null);
+        this.#keysChanged();
+    }
+    /** The labels `commands.keys` last answered or pushed, as JSON. */
+    #keysSent = "";
+    /** The binding table revision of `commands.keys` (a counter here). */
+    #keysRevision = 0;
+    /**
+     * `commands.keys` as the player answers it: each of the plugin's own
+     * commands with the labels of the keys it holds now (the overlay, else
+     * its defaults; not a key an earlier command holds), as menus write
+     * them on `systemInfo.os`.
+     */
+    #keys() {
+        const claims = this.#claims();
+        const mac = this.systemInfo.os === "macos";
+        const keys = {};
+        for (const [id, { declaration }] of this.commands) {
+            const scope = declaration.focus ? "panel" : "global";
+            const current = this.bindings.overlay.get(this.#bindingKey(id)) ??
+                declaration.bindings ??
+                [];
+            const labels = [];
+            for (const input of current) {
+                if (claims.get(`${scope} ${input}`)?.[0] !== id)
+                    continue;
+                const label = keyLabel(input, mac);
+                if (label !== null && !labels.includes(label))
+                    labels.push(label);
+            }
+            keys[id] = labels;
+        }
+        return { keys, revision: this.#keysRevision };
+    }
+    /** Push `commands.keys` when the labels changed and the plugin listens. */
+    #keysChanged() {
+        this.#keysRevision++;
+        if (!this.subscriptions.has("commands.keys"))
+            return;
+        const now = this.#keys();
+        const text = JSON.stringify(now.keys);
+        if (text === this.#keysSent)
+            return;
+        this.#keysSent = text;
+        this.emit("commands.keys", now);
+    }
     /**
      * The binding overlay `plugin.bindings.set` writes (`"<plugin>/<command>"`
      * to inputs; preset it to simulate saved overrides). `press` honours it.
@@ -4182,11 +4263,20 @@ export class TestHost {
                     await host.settle();
                 },
             });
+            // The player pushes the new command's keys after the answer.
+            queueMicrotask(() => this.#keysChanged());
             return { revision: 1 };
         },
         "commands.unregister": (p) => {
             if (!this.commands.delete(String(p.id)))
                 throw new HostError("missing", `command ${p.id} is not registered`);
+            queueMicrotask(() => this.#keysChanged());
+        },
+        // Player 0.7.6: the labels of the plugin's own commands.
+        "commands.keys": () => {
+            const now = this.#keys();
+            this.#keysSent = JSON.stringify(now.keys);
+            return now;
         },
         "commands.update": (p) => {
             // The request itself, as the player reads it (capabilities/commands.rs
@@ -5102,6 +5192,7 @@ export class TestHost {
                 throw new HostError("missing", `no command ${key}`);
             this.bindings.overlay.set(key, [...p.inputs]);
             this.emit("bindings.changed", null);
+            this.#keysChanged();
         },
         "bindings.reset": (p) => {
             if (p.plugin === undefined)
@@ -5109,6 +5200,7 @@ export class TestHost {
             else
                 this.bindings.overlay.delete(`${p.plugin}/${p.command}`);
             this.emit("bindings.changed", null);
+            this.#keysChanged();
         },
         "packages.list": () => structuredClone(this.packages),
         "packages.setEnabled": (p) => {

package/dist/plugin/types.d.ts

@@ -1451,6 +1451,81 @@ export interface Commands {
      * @since 1.0.0
      */
     add(options: CommandOptions): Command;
+    /**
+     * The keys of one of this plugin's own commands (its local id, as in
+     * {@link CommandOptions.id}), written as the player's menus and command
+     * palette write them: `["W"]`, `["Ctrl+B"]`, `["⌘B"]` on macOS, arrows as
+     * `←`. Read-only, and always what is bound now: the user's own keys
+     * after a change in Keyboard Shortcuts, none when the user cleared them
+     * or turned on Ignore Default Shortcuts, and none for a key another
+     * command holds. Mouse bindings are left out, and so are `Cmd`
+     * bindings outside macOS (as in the menus). The first label is the one
+     * the menus show.
+     *
+     * @remarks
+     * For key hints beside a panel's controls (`KeyHint` and the `keys` of
+     * `ToolTipArea` in `@vestra/widgets.slint`). Read it in a
+     * {@link View.bind} function and the view follows every change; or
+     * listen with {@link Commands.onKeysChange}. The first read asks the
+     * player, and until its answer arrives (a few milliseconds) every
+     * command reads `[]`; a binding that read it runs again then.
+     *
+     * Only the plugin's own commands: an id the plugin has not added (or
+     * another plugin's) reads `[]`. Needs nothing beyond `commands`, not
+     * `bindings.manage` (the whole binding table, every plugin's, is
+     * {@link Bindings.list}). Without the `commands` capability every
+     * command reads `[]`. Players before 0.7.6 have no `keys` (the player
+     * builds `plugin` from its own SDK) and no `KeyHint` in their widgets,
+     * so declare `"minPlayerVersion": "0.7.6"`.
+     *
+     * @example Show a slider's keys beside it
+     * The Brightness row shows its two keys, W and E by default, as key caps
+     * (`KeyHint` in `ui/picture.slint`). `keys` is read inside the `bind` function,
+     * so the view gets the new labels whenever the user changes a key or
+     * clears it (an empty list hides the cap).
+     * ```ts
+     * const pictureWindow = plugin.windows.create("ui/picture.slint");
+     * plugin.commands.add({ id: "brightness.down", path: ["@video", "Brightness −"], bindings: ["W"], run() {} });
+     * plugin.commands.add({ id: "brightness.up", path: ["@video", "Brightness +"], bindings: ["E"], run() {} });
+     * pictureWindow.bind(() => ({
+     *   // Read in bind: the view follows every key change; "" hides a cap.
+     *   brightnessDown: plugin.commands.keys("brightness.down")[0] ?? "",
+     *   brightnessUp: plugin.commands.keys("brightness.up")[0] ?? "",
+     * }));
+     * ```
+     *
+     * @capability commands
+     * @player 0.7.6 (declare `"minPlayerVersion": "0.7.6"`; older players
+     *   have no `keys`: calling it throws a `TypeError`).
+     * @since 1.6.6
+     */
+    keys(id: string): readonly string[];
+    /**
+     * Run `listener` after the keys of any of this plugin's commands changed
+     * (read them again with {@link Commands.keys}): the user changed or
+     * cleared a key, turned Ignore Default Shortcuts on or off, a command with
+     * keys was added or removed, or the player's first answer arrived. At most every
+     * 200 ms. A plugin in standby that listens is started for it, as for a
+     * key change in {@link Bindings.onChange}.
+     *
+     * @capability commands
+     *
+     * @example Name the current key in a status line
+     * The OSD tells the user the new key after they change it. The listener
+     * carries no data; it reads the labels with `keys`.
+     * ```ts
+     * plugin.commands.onKeysChange(() => {
+     *   const [key] = plugin.commands.keys("toggle-blur");
+     *   if (key) void plugin.osd.show("Blur: {}", [key]);
+     *   else void plugin.osd.show("Blur has no key");
+     * });
+     * ```
+     *
+     * @player 0.7.6 (declare `"minPlayerVersion": "0.7.6"`; older players
+     *   have no `onKeysChange`).
+     * @since 1.6.6
+     */
+    onKeysChange(listener: () => void): Disposable;
 }
 /**
  * An image file for a Slint `image` property, made by {@link Ui.image}.

package/dist/wire.d.ts

@@ -441,7 +441,7 @@ export interface Transport {
     locale?: string;
 }
 /** The events a plugin subscribes to (`events.subscribe`). */
-type HostEvent = "source.state" | "playback.backend" | "window.state" | "packages.changed" | "bindings.changed" | "timeline.changed" | "appearance.changed" | "resolvers.fileTypes" | "video.upscaling.changed";
+type HostEvent = "source.state" | "playback.backend" | "window.state" | "packages.changed" | "bindings.changed" | "commands.keys" | "timeline.changed" | "appearance.changed" | "resolvers.fileTypes" | "video.upscaling.changed";
 export declare function createWire(transport: Transport): {
     processing: {
         state: () => Promise<import("./processing.ts").ProcessingState>;
@@ -453,6 +453,7 @@ export declare function createWire(transport: Transport): {
             revision: number;
         }>;
         unregister: (id: string) => Promise<void>;
+        keys: () => Promise<import("./commands.ts").CommandKeys>;
         update: (id: string, revision: number, state: import("./commands.ts").CommandState, when?: import("./commands.ts").CommandWhen) => Promise<{
             revision: number;
         }>;

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.6.5: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
+> @vestra-player/sdk 1.6.7: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
 
 ## Read the documentation
 

package/package.json

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

package/slint/vestra/widgets.slint

@@ -1,5 +1,5 @@
 // Compact controls built on the Vestra theme (core-ui-design.md §2.1):
-//   import { Button, Slider, ToolTipArea, UrlInputRow } from "@vestra/widgets.slint";
+//   import { Button, KeyHint, Slider, ToolTipArea, ToolTipKey, UrlInputRow } from "@vestra/widgets.slint";
 //   import { Choice, Check, Radio, RadioGroup, RadioMark, Tab, Tabs } from "@vestra/widgets.slint";
 // Icons: @vestra/icons.slint. Other controls come from std-widgets, which the
 // host compiles as fluent-dark and switches to light for a light palette.
@@ -9,10 +9,48 @@
 // so a click on a panel control leaves the player's shortcuts (Space, the
 // arrows) with the video, as on macOS. A focused control shows a 1px accent
 // ring.
-import { TextEdit, ListView } from "std-widgets.slint";
+import { TextEdit, ListView, Palette } from "std-widgets.slint";
 import { Theme } from "theme.slint";
 import { Icon } from "icons.slint";
 
+// A key cap: the label of a shortcut as the player's menus write it
+// (`plugin.commands.keys`: `W`, `Ctrl+B`, `⌘B` on macOS), in small
+// monospace `text-dim` type inside a 1px border. Put it at the right end of
+// a control's row, the minus key before the plus key (`W` `E`). An empty
+// `text` draws nothing and takes no space, so a command without a key (or
+// one the user cleared) shows no cap; the element stays the same either way.
+export component KeyHint {
+    in property <string> text;
+    private property <bool> shown: root.text != "";
+    visible: root.shown;
+    width: root.shown ? max(16px, label.preferred-width + 8px) : 0px;
+    height: root.shown ? 15px : 0px;
+    accessible-role: AccessibleRole.text;
+    accessible-label: root.text;
+    Rectangle {
+        border-width: 1px;
+        border-radius: 3px;
+        // The cap's edge: a step above the panel in both palettes.
+        border-color: Theme.icon-disabled;
+        background: Theme.bg-list;
+        label := Text {
+            text: root.text;
+            font-family: Theme.font-mono;
+            font-size: Theme.font-xs;
+            color: Theme.text-dim;
+            horizontal-alignment: center;
+            vertical-alignment: center;
+        }
+    }
+}
+
+// One key in a tooltip (`ToolTipArea.keys`): its label (`KeyHint`) and what
+// it does, a word or a sign (`−`, `+`). An empty `key` is left out.
+export struct ToolTipKey {
+    key: string,
+    text: string,
+}
+
 // Hover for about half a second to show `text` beside the pointer. The tip
 // closes when the pointer leaves, or presses on content that does not take
 // the press itself; it shows again on the next hover. It is Slint's
@@ -20,8 +58,16 @@ import { Icon } from "icons.slint";
 // pointer, and the tip does not take the keyboard focus. (Up to SDK 1.5.20 the tip was a
 // PopupWindow, which swallowed the first press after it showed and took the
 // focus while it was open.)
+// With `keys` (SDK 1.6.6) the tip names the control's keys after its title,
+// each as a key cap and what it does: "Brightness  [W] −  [E] +"; `detail`
+// follows dimmed ("· double-click: Default"). Changing `keys` or `detail`
+// changes the tip's text, never which elements exist while hovering.
 export component ToolTipArea {
     in property <string> text;
+    in property <[ToolTipKey]> keys;
+    in property <string> detail;
+    // The tip names keys or a detail: drawn with key caps.
+    private property <bool> rich: root.keys.length > 0 || root.detail != "";
     // The tip is showing (read-only); it follows the tip's delay closely,
     // not exactly.
     out property <bool> showing;
@@ -44,10 +90,56 @@ export component ToolTipArea {
             }
         }
         // Removing it closes an open tip.
-        if root.text != "" && !root.done: Tooltip {
+        if root.text != "" && !root.done && !root.rich: Tooltip {
             // Interpolated text is plain: `*` or `_` in it are not markup.
             text: @markdown("\{root.text}");
         }
+        // The tip with key caps, drawn as the text tip is (std-widgets'
+        // ToolTipImpl). Its own element: one Tooltip per parent.
+        if root.text != "" && !root.done && root.rich: Rectangle {
+            width: 100%;
+            height: 100%;
+            Tooltip {
+                Rectangle {
+                    background: Palette.alternate-background;
+                    border-radius: 4px;
+                    border-width: 1px;
+                    border-color: Palette.border;
+                    HorizontalLayout {
+                        padding-left: 9px;
+                        padding-right: 9px;
+                        padding-top: 6px;
+                        padding-bottom: 6px;
+                        Text {
+                            text: root.text;
+                            color: Palette.foreground;
+                            vertical-alignment: center;
+                        }
+                        for entry in root.keys: HorizontalLayout {
+                            padding-left: entry.key == "" ? 0px : 10px;
+                            spacing: entry.key == "" ? 0px : 4px;
+                            VerticalLayout {
+                                alignment: center;
+                                KeyHint { text: entry.key; }
+                            }
+                            Text {
+                                text: entry.key == "" ? "" : entry.text;
+                                color: Palette.foreground;
+                                vertical-alignment: center;
+                            }
+                        }
+                        HorizontalLayout {
+                            padding-left: root.detail == "" ? 0px : 10px;
+                            Text {
+                                text: root.detail;
+                                color: Theme.text-dim;
+                                vertical-alignment: center;
+                            }
+                        }
+                    }
+                }
+            }
+        }
     }
     Timer {
         interval: 500ms;