@vestra-player/sdk 1.6.5 → 1.6.8

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.6.8
+
+**Who must change: nobody; authors of a bottom bar should move to `content-min-width`.** Documentation, a read-only Slint property and a removed CLI warning: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability. A plugin's `button` declarations stay as they are. A bottom bar that still places `BarButtons` keeps working on player 0.7.6 (it shows that strip, and the player draws no second one); it is deprecated and goes in a later patch.
+
+- **The player places the bottom bar's button strip** (player 0.7.6, menu redesign step 3a). It draws the strip at the right end of the bottom slot, also when no plugin mounts a bottom bar (in a band of its own): the plugins' buttons, a » menu, the player's **Command Palette** (`host/palette`, a magnifier) and **Toggle Sidebar**. [Bottom-bar buttons](docs/explanation/commands.md#bottom-bar-buttons) now reads: buttons are ordered by `order`, then by plugin id; lower `order` comes first and stays visible longest; when the strip runs out of room, or more than 8 plugin buttons are declared, the remaining buttons move to the » menu, in the same order; a button is never dropped. Before player 0.7.6 a narrow strip lost its lowest orders first and the player left out all but the eight highest; `BAR_BUTTON_LIMITS.total` is now what the strip holds. [Reference: commands](docs/reference/commands.md#bottom-bar-buttons), [Reference: limits](docs/reference/limits.md#bottom-bar-buttons), `CommandButton`, `CommandOptions.button` and `BAR_BUTTON_LIMITS` say so.
+- **Writing a bottom bar** ([Interface guidelines](docs/guidelines/interface.md#writing-a-bottom-bar)): a bar places nothing. It reports the least width of its own controls in a `content-min-width` length property on the mounted component (the player gives the strip the rest, so the time label is never covered) and ends its row at the strip, reading `BarButtonsHost.width` (new, read only; `fixed` for an optional control kept ahead of plugin buttons) from `@vestra/bar-buttons.slint`. The file stays in the Slint library copy for that global; its `BarButtons` component is deprecated.
+- **`@vestra/bar-buttons.slint`** (the read-only copy of the player's widget library, synced): `BarButtonsHost` gains `width`, `fixed`, `shown` and `more` (out: the strip's width, the cells a bar must leave free (the player's own and the » cell), the plugin buttons in the strip, whether » shows) and the player's `palette`, `overflow` and `room`; the comments describe the player's strip and mark `BarButtons` deprecated.
+- **`vestra-plugin check` no longer warns** that a bottom bar does not place `BarButtons`: since player 0.7.6 that is the right thing to do.
+
+## 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/bin/vestra-plugin.mjs

@@ -81,7 +81,6 @@ import {
   basename,
   dirname,
   extname,
-  isAbsolute,
   join,
   relative,
   resolve,
@@ -363,10 +362,7 @@ 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)),
-    ...(await forWarnings(target)),
-  ])
+  for (const line of await forWarnings(target))
     console.log(`${target.name}: warning: ${line}`);
   // Translation warnings never fail the check.
   if (present(join(target.directory, "locales"))) {
@@ -432,85 +428,6 @@ function slintCode(text) {
   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;
-}
-
 /**
  * A `for` over an array the plugin binds (an `in` or `in-out` property of
  * array type of a component or global in the same file), outside a

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

@@ -158,12 +158,11 @@ export declare const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back"
 /**
  * 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).
+ * past `perPlugin` has none (its command still registers and its menu entry
+ * stays). `total` is what the strip holds: the `total` lowest by order,
+ * plugin id and declaration order; the rest are in the strip's » menu, in
+ * the same order (older players keep the `total` highest and leave the
+ * others out).
  *
  * @since 1.5.29
  *
@@ -172,7 +171,7 @@ export declare const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back"
 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). */
+    /** Buttons in the strip, every plugin together, besides the player's own (8); the rest are in its » menu. */
     readonly total: 8;
     /** The highest `order` (999; the lowest is 0). */
     readonly maxOrder: 999;
@@ -345,12 +344,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

@@ -202,12 +202,11 @@ export const BAR_BUTTON_ICONS = [
 /**
  * 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).
+ * past `perPlugin` has none (its command still registers and its menu entry
+ * stays). `total` is what the strip holds: the `total` lowest by order,
+ * plugin id and declaration order; the rest are in the strip's » menu, in
+ * the same order (older players keep the `total` highest and leave the
+ * others out).
  *
  * @since 1.5.29
  *
@@ -216,7 +215,7 @@ export const BAR_BUTTON_ICONS = [
 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). */
+    /** Buttons in the strip, every plugin together, besides the player's own (8); the rest are in its » menu. */
     total: 8,
     /** The highest `order` (999; the lowest is 0). */
     maxOrder: 999,
@@ -692,6 +691,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.
@@ -2617,8 +2645,8 @@ export declare class TestHost implements Transport {
      * The plugin's bottom-bar buttons (`CommandOptions.button`) as the player
      * shows them: at most one, the first declared (`BAR_BUTTON_LIMITS`; a
      * later one stays a menu item only). Empty once the command is disposed.
-     * Whether the bar places them is the bar's business: the list is what
-     * the player hands to `BarButtons`.
+     * Whether one is in the strip or its » menu is the player's business
+     * (the room and the other plugins' buttons).
      *
      * @example Click the plugin's bottom-bar button in a test
      * The test finds the plugin's Store button, clicks it and checks that the

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.
@@ -3324,8 +3405,8 @@ export class TestHost {
      * The plugin's bottom-bar buttons (`CommandOptions.button`) as the player
      * shows them: at most one, the first declared (`BAR_BUTTON_LIMITS`; a
      * later one stays a menu item only). Empty once the command is disposed.
-     * Whether the bar places them is the bar's business: the list is what
-     * the player hands to `BarButtons`.
+     * Whether one is in the strip or its » menu is the player's business
+     * (the room and the other plugins' buttons).
      *
      * @example Click the plugin's bottom-bar button in a test
      * The test finds the plugin's Store button, clicks it and checks that the
@@ -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

@@ -954,17 +954,17 @@ export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "op
  * A command's button on the bottom bar: {@link CommandOptions.button}.
  *
  * @remarks
- * **Where it shows.** The bottom bar places the player's strip of command
- * buttons, `BarButtons` from `@vestra/bar-buttons.slint`, at its right end;
- * the player fills it with the buttons of every plugin, left to right by
- * `order`, and its own sidebar toggle rightmost. When the window is narrow
- * the strip loses cells from its outer (left) end inward: the lowest order
- * goes first, the sidebar toggle last. A
- * bottom bar that does not place `BarButtons` shows no buttons: the
- * command's menu entry stays, and the player logs the buttons it cannot
- * show and whose bar hides them. The built-in bar (`vestra.playback`) places
- * it; see
- * [Writing a bottom bar](../../docs/guidelines/interface.md#writing-a-bottom-bar).
+ * **Where it shows.** The player draws the bottom bar's button strip and
+ * decides where it goes: today at the right end of the bottom bar; this may
+ * change (older players let the bar place `BarButtons` itself). Buttons
+ * are ordered by `order`, then by plugin id; lower `order` comes first and
+ * stays visible longest. When the strip runs out of room, or more than 8
+ * plugin buttons are declared, the remaining buttons move to the strip's »
+ * menu, in the same order. A button is never dropped: it is either in the
+ * strip or in the » menu, and its command keeps its menu entry, its key and
+ * its place in the command palette. Users may pin and unpin buttons later;
+ * do not rely on a position. See
+ * [Bottom-bar buttons](../../docs/explanation/commands.md#bottom-bar-buttons).
  *
  * **What it shows.** The icon, the command's title (translated, a trailing
  * "…" removed) and its first key as the tooltip ("Plugin Store (F9)"),
@@ -974,9 +974,9 @@ export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "op
  * 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
- * menu entry stay) and the player logs it with `limit`. The button goes
+ * **Limits.** One button per plugin, the first it declares (a later one
+ * stays a menu item only), and eight in the strip (`BAR_BUTTON_LIMITS`); the
+ * rest are in the » menu. The button goes
  * with its command: disposing the command, or disabling, stopping or
  * uninstalling the plugin, removes it.
  *
@@ -984,8 +984,7 @@ export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "op
  * A Store icon appears in the bottom bar's button strip; a click opens
  * the store window, exactly like the menu item. The player draws the
  * button from the command's title, keys and state, and places it by
- * `order` (200 is where the player's own Plugin Store button sits); a
- * bar that does not place `BarButtons` shows only the menu item.
+ * `order` (200 is where the player's own Plugin Store button sits).
  * ```ts
  * const store = plugin.windows.create("ui/store.slint");
  * plugin.commands.add({
@@ -1238,8 +1237,8 @@ export 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
+     * menu entry is where the command stays reachable wherever the button
+     * is (the strip or its » menu). See
      * {@link CommandButton} for where it shows, what it shows and the limits.
      * Fails with `invalid` for an unknown icon name, an order outside 0–999 or
      * a button without a path.
@@ -1451,6 +1450,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.8: 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.8",
   "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

@@ -1,15 +1,26 @@
-// Command buttons of a bottom bar (player 0.5.10, SDK 1.5.29): the buttons
+// Command buttons of the bottom bar (player 0.5.10, SDK 1.5.29): the buttons
 // that plugins' commands contribute (`commands.add({ button })`) and the
-// player's sidebar toggle, rightmost. The player fills `BarButtonsHost` in
-// every window it composes and runs the clicks; a bottom bar places one
-// `BarButtons` in its own layout and gives it the width it can spare:
-//   import { BarButtons } from "@vestra/bar-buttons.slint";
-//   strip := BarButtons { x: parent.width - self.width - 4px; room: ...; }
-// It shows as many 41×40 cells as fit in `room`, the strip as wide as the
-// cells shown (`width`). Cells go from the strip's outer (left) end inward:
-// of the plugins' buttons (ascending `order`, left to right) the lowest
-// order goes first, and the sidebar toggle goes last. A bar without a `BarButtons` shows none of them (their menu
-// entries stay; the player logs which buttons are hidden).
+// player's own. Since SDK 1.6.8 (menu redesign step 3a) the player draws
+// the strip itself, at the right end of the bottom slot, its 40px cells on
+// the slot's bottom edge (a bar's 40px button row), and also when no plugin
+// mounts a bottom bar: `[plugin buttons…][»][Command Palette][Toggle
+// Sidebar]`. A bottom bar places nothing: it lays its controls out left of
+// the strip and says how wide they must stay:
+//   import { BarButtonsHost } from "@vestra/bar-buttons.slint";
+//   export component MyBar inherits Rectangle {
+//       out property <length> content-min-width: ...; // the least your row needs
+//       // your row ends at: root.width - BarButtonsHost.width - 4px
+//   }
+// The player gives its strip `bar width - content-min-width - 4px` (all of
+// the width without `content-min-width`), so plugin buttons never cover
+// what the bar needs (its time label, UI-BAR-10). Plugin buttons go left to
+// right by ascending `order`, then plugin id, then registration; at most 8
+// are in the strip, and the ones past 8 or past the room are in the `»`
+// menu, in the same order: the lowest order stays longest. `»` shows only
+// while something is in it; the player's own cells always show.
+//
+// `BarButtons` (below) is deprecated: the strip a bar placed itself before
+// SDK 1.6.8. While a bar still places it, the player draws no second strip.
 //
 // The cells look like the bar's own icon buttons: a 32×32 plate on hover
 // and press, the bar's tooltip (ToolTipArea). Every enabled cell draws its
@@ -43,14 +54,56 @@ export struct BarButtonItem {
     dimmed: bool,
 }
 
-// Filled by the player; a bar reads it only through `BarButtons`.
+// Filled by the player. A bar reads `width` (to end its own row left of
+// the strip) and `fixed`; everything else is the player's.
 export global BarButtonsHost {
-    // The plugins' buttons, left to right, at most 8.
+    // The plugins' buttons for the strip, left to right, at most 8.
     in property <[BarButtonItem]> buttons;
+    // How many plugin buttons are past those 8 (always in the `»` menu).
+    in property <int> overflow;
     // The sidebar toggle (`token` "" while there is none).
     in property <BarButtonItem> toggle;
-    // Set when a `BarButtons` exists in this window.
+    // The command palette (`host/palette`; `token` "" while there is none).
+    in property <BarButtonItem> palette;
+    // Set when a (deprecated) `BarButtons` exists in this window.
     in-out property <bool> placed;
+    // The width the player gives its strip (the player sets it).
+    in-out property <length> room;
+    // The player's own cells, always shown (step 3b adds Adjust).
+    private property <int> own: (root.palette.token != "" ? 1 : 0) + (root.toggle.token != "" ? 1 : 0);
+    // The cells a bar must always leave free, 41px each: the player's own,
+    // and the `»` cell whenever any plugin button exists (drawn only on
+    // overflow, but always reserved, so `»` never covers the bar). Never
+    // depends on `room`. A bar that keeps an optional control ahead of the
+    // plugins' buttons counts it in `content-min-width` while it fits
+    // beside these.
+    out property <int> fixed: root.own + (root.buttons.length > 0 || root.overflow > 0 ? 1 : 0);
+    // The strip's layout for a room, as pure functions, so the player's
+    // strip binds them to its own `room` (no frame behind the shell's
+    // layout) and the properties below give the same numbers for `room`.
+    // The plugin buttons in the strip (the first of `buttons`) at `room`.
+    public pure function shown-in(room: length) -> int {
+        // Cells left for plugin buttons and `»`.
+        let free = Math.max(0, Math.floor(room / 41px) - root.own);
+        if root.overflow == 0 && root.buttons.length <= free {
+            return root.buttons.length;
+        }
+        return Math.max(0, Math.min(root.buttons.length, free - 1));
+    }
+    // Whether `»` shows at `room` (a button past 8 or past the room).
+    public pure function more-in(room: length) -> bool {
+        return root.shown-in(room) < root.buttons.length || root.overflow > 0;
+    }
+    // The strip's width at `room` (0 while a bar places `BarButtons`).
+    public pure function width-in(room: length) -> length {
+        if root.placed {
+            return 0px;
+        }
+        return (root.shown-in(room) + (root.more-in(room) ? 1 : 0) + root.own) * 41px;
+    }
+    out property <int> shown: root.shown-in(root.room);
+    out property <bool> more: root.more-in(root.room);
+    out property <length> width: root.width-in(root.room);
     // A click on the cell with this token.
     callback clicked(string);
 }
@@ -127,8 +180,11 @@ component Cell inherits Rectangle {
     }
 }
 
-// The strip: place it at the bar's right end and give it the width you can
-// spare; it is as wide as the cells it shows (read `width` to lay out the rest).
+// Deprecated (SDK 1.6.8; the player places its strip): the strip a bar
+// placed at its right end with the width it could spare. A bar that still
+// places it shows this one instead of the player's (no palette cell, no
+// `»`): the cells that fit in `room`, lost from its outer (left) end
+// inward, the sidebar toggle last; it is as wide as the cells it shows.
 export component BarButtons {
     // The width the bar can give the strip; the cells that fit show.
     in property <length> room;

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;