@vestra-player/sdk 1.5.13 → 1.5.14

package/dist/plugin/bindings.js

@@ -7,54 +7,103 @@
  *   input    = key | "Mouse:" mouse
  */
 import { failure } from "./runtime.js";
-const MODIFIERS = ["Ctrl", "Alt", "Shift", "Cmd"];
+/**
+ * The names a binding (`CommandOptions.bindings`, `Bindings.set`) is made
+ * of, as the player's binding parser accepts them. A binding is
+ * `{ modifier "+" } input`: modifiers in the order of `modifiers`, each at
+ * most once, then one input. An input is a name of `letters`, `digits`,
+ * `functionKeys`, `named` or `mouse`, or one other printable character that
+ * is not a letter, digit, space or `+` (`">"`, `"["`, `"/"`), written as
+ * typed, never with `Shift` (`">"`, not `"Shift+."`; `"!"`, not
+ * `"Shift+1"`). Anything else fails with code `invalid`. The player's tests
+ * check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { BINDING_INPUTS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(BINDING_INPUTS.named.includes("PageUp"));
+ * assert.ok(BINDING_INPUTS.mouse.includes("Mouse:WheelUp"));
+ * ```
+ *
+ * @since 1.5.14
+ */
+export const BINDING_INPUTS = Object.freeze({
+    /**
+     * Modifiers, in the order a binding writes them. `Cmd` is ⌘ on macOS and
+     * the Windows logo key on Windows; on macOS `Ctrl` also matches ⌘.
+     */
+    modifiers: ["Ctrl", "Alt", "Shift", "Cmd"],
+    /** Letter keys, by key name whatever the case: `A` to `Z`. */
+    letters: [..."ABCDEFGHIJKLMNOPQRSTUVWXYZ"],
+    /** Digit keys of the main keyboard: `0` to `9`. */
+    digits: [..."0123456789"],
+    /** Function keys: `F1` to `F24`. */
+    functionKeys: Array.from({ length: 24 }, (_, index) => `F${index + 1}`),
+    /**
+     * Other named keys, matched by the physical key. `Plus` is the `+` key
+     * however it is typed; the `Numpad…` names are the numeric keypad only,
+     * never the main keyboard.
+     */
+    named: [
+        "Space",
+        "Enter",
+        "Tab",
+        "Escape",
+        "Backspace",
+        "Delete",
+        "Insert",
+        "Home",
+        "End",
+        "PageUp",
+        "PageDown",
+        "ArrowLeft",
+        "ArrowRight",
+        "ArrowUp",
+        "ArrowDown",
+        "Plus",
+        ...Array.from({ length: 10 }, (_, digit) => `Numpad${digit}`),
+        "NumpadPlus",
+        "NumpadMinus",
+        "NumpadMultiply",
+        "NumpadDivide",
+        "NumpadEnter",
+        "NumpadDecimal",
+    ],
+    /**
+     * Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the
+     * halves of the video apart for a double click.
+     */
+    mouse: [
+        "Mouse:LeftClick",
+        "Mouse:LeftDoubleClick",
+        "Mouse:LeftDoubleClick:LeftHalf",
+        "Mouse:LeftDoubleClick:RightHalf",
+        "Mouse:MiddleClick",
+        "Mouse:X1",
+        "Mouse:X2",
+        "Mouse:WheelUp",
+        "Mouse:WheelDown",
+        "Mouse:WheelLeft",
+        "Mouse:WheelRight",
+    ],
+});
+const MODIFIERS = BINDING_INPUTS.modifiers;
 const NAMED = new Set([
-    "Space",
-    "Enter",
-    "Tab",
-    "Escape",
-    "Backspace",
-    "Delete",
-    "Insert",
-    "Home",
-    "End",
-    "PageUp",
-    "PageDown",
-    "ArrowLeft",
-    "ArrowRight",
-    "ArrowUp",
-    "ArrowDown",
-    "Plus",
-    // Numeric keypad: never matched by the main keyboard keys, nor they by these.
-    ..."0123456789".split("").map((digit) => `Numpad${digit}`),
-    "NumpadPlus",
-    "NumpadMinus",
-    "NumpadMultiply",
-    "NumpadDivide",
-    "NumpadEnter",
-    "NumpadDecimal",
-]);
-const MOUSE = new Set([
-    "LeftClick",
-    "LeftDoubleClick",
-    "LeftDoubleClick:LeftHalf",
-    "LeftDoubleClick:RightHalf",
-    "MiddleClick",
-    "X1",
-    "X2",
-    "WheelUp",
-    "WheelDown",
-    "WheelLeft",
-    "WheelRight",
+    ...BINDING_INPUTS.functionKeys,
+    ...BINDING_INPUTS.named,
 ]);
+const MOUSE = new Set(BINDING_INPUTS.mouse);
+const LETTERS = new Set(BINDING_INPUTS.letters);
+const DIGITS = new Set(BINDING_INPUTS.digits);
 function kind(input) {
     if (input.startsWith("Mouse:"))
-        return MOUSE.has(input.slice(6)) ? "mouse" : null;
-    if (/^[A-Z]$/.test(input))
+        return MOUSE.has(input) ? "mouse" : null;
+    if (LETTERS.has(input))
         return "letter";
-    if (/^[0-9]$/.test(input))
+    if (DIGITS.has(input))
         return "digit";
-    if (/^F([1-9]|1[0-9]|2[0-4])$/.test(input) || NAMED.has(input))
+    if (NAMED.has(input))
         return "named";
     // One printable, non-alphanumeric, non-space character; "+" is written Plus.
     if ([...input].length === 1 && /^[^\p{L}\p{N}\s+]$/u.test(input))

package/dist/plugin/osd.d.ts

@@ -1,6 +1,38 @@
 import type { ScopeImpl } from "./scope.ts";
 import type { Osd } from "./types.ts";
 import type { TemplateArgsJson, TextValueJson } from "../wire.ts";
+/**
+ * The player's limits on the on-screen display ({@link Osd}), counted on
+ * the text as shown: after the player translated it and filled in its
+ * arguments. A text over them fails with code `invalid`: `osd.show`
+ * rejects, `OsdPanel.set` reports to `Scope.onError`. The player's tests
+ * check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { OSD_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * const lines = rows.slice(0, OSD_LIMITS.panelLines);
+ * panel.set(lines.join("\n"), null, { maxColumns: 60 });
+ * ```
+ *
+ * @since 1.5.14
+ */
+export declare const OSD_LIMITS: Readonly<{
+    /**
+     * Characters of one `osd.show` message (200; at least 1 that is not
+     * white space). Line breaks are shown as spaces.
+     */
+    readonly messageChars: 200;
+    /** Lines of the information block (`OsdPanel.set`) (32). */
+    readonly panelLines: 32;
+    /** UTF-8 bytes of the information block (4096). */
+    readonly panelBytes: 4096;
+    /** The smallest `OsdPanelOptions.maxColumns` (8). */
+    readonly minColumns: 8;
+    /** The largest `OsdPanelOptions.maxColumns` (1000). */
+    readonly maxColumns: 1000;
+}>;
 /**
  * Copy and check template arguments: an array or object of at most 16
  * strings, finite numbers, texts and lists (`TEXT_LIMITS`).

package/dist/plugin/osd.js

@@ -2,6 +2,38 @@
 import { Latest } from "./runtime.js";
 import { failure } from "./runtime.js";
 import { isTextValue, textProblem } from "../i18n.js";
+/**
+ * The player's limits on the on-screen display ({@link Osd}), counted on
+ * the text as shown: after the player translated it and filled in its
+ * arguments. A text over them fails with code `invalid`: `osd.show`
+ * rejects, `OsdPanel.set` reports to `Scope.onError`. The player's tests
+ * check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { OSD_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * const lines = rows.slice(0, OSD_LIMITS.panelLines);
+ * panel.set(lines.join("\n"), null, { maxColumns: 60 });
+ * ```
+ *
+ * @since 1.5.14
+ */
+export const OSD_LIMITS = Object.freeze({
+    /**
+     * Characters of one `osd.show` message (200; at least 1 that is not
+     * white space). Line breaks are shown as spaces.
+     */
+    messageChars: 200,
+    /** Lines of the information block (`OsdPanel.set`) (32). */
+    panelLines: 32,
+    /** UTF-8 bytes of the information block (4096). */
+    panelBytes: 4096,
+    /** The smallest `OsdPanelOptions.maxColumns` (8). */
+    minColumns: 8,
+    /** The largest `OsdPanelOptions.maxColumns` (1000). */
+    maxColumns: 1000,
+});
 /**
  * Copy and check template arguments: an array or object of at most 16
  * strings, finite numbers, texts and lists (`TEXT_LIMITS`).
@@ -54,8 +86,10 @@ class PanelHandle {
         try {
             const max = options?.maxColumns;
             if (max !== undefined &&
-                !(Number.isInteger(max) && max >= 8 && max <= 1000))
-                throw failure("invalid", "maxColumns is an integer from 8 to 1000");
+                !(Number.isInteger(max) &&
+                    max >= OSD_LIMITS.minColumns &&
+                    max <= OSD_LIMITS.maxColumns))
+                throw failure("invalid", `maxColumns is an integer from ${OSD_LIMITS.minColumns} to ${OSD_LIMITS.maxColumns}`);
             value = {
                 text: text === null ? null : shownText(text, args),
                 ...(text === null || args === undefined || args === null

package/dist/plugin/services.d.ts

@@ -6,4 +6,29 @@ export declare const power: (scope: ScopeImpl) => Power;
 export declare function tools(scope: ScopeImpl): Tools;
 export declare const storage: (scope: ScopeImpl) => Storage;
 export declare function system(scope: ScopeImpl): System;
+/**
+ * The player's limits on {@link Secrets}. A name or value outside them
+ * fails with code `invalid`; a new name beyond `names` fails with `limit`.
+ * The player's tests check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(Buffer.byteLength(token) <= SECRET_LIMITS.valueBytes);
+ * ```
+ *
+ * @since 1.5.14
+ */
+export declare const SECRET_LIMITS: Readonly<{
+    /**
+     * Characters of a name (64, at least 1), each one of `a-z`, `0-9`, `.`,
+     * `_` and `-`.
+     */
+    readonly nameChars: 64;
+    /** UTF-8 bytes of a value (1024, at least 1; no NUL character). */
+    readonly valueBytes: 1024;
+    /** Different names one plugin may have stored at the same time (256). */
+    readonly names: 256;
+}>;
 export declare const secrets: (scope: ScopeImpl) => Secrets;

package/dist/plugin/services.js

@@ -292,13 +292,38 @@ export function system(scope) {
         },
     };
 }
-const SECRET = /^[a-z0-9._-]{1,64}$/;
+/**
+ * The player's limits on {@link Secrets}. A name or value outside them
+ * fails with code `invalid`; a new name beyond `names` fails with `limit`.
+ * The player's tests check that these agree with the player.
+ *
+ * @example
+ * ```ts
+ * import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * assert.ok(Buffer.byteLength(token) <= SECRET_LIMITS.valueBytes);
+ * ```
+ *
+ * @since 1.5.14
+ */
+export const SECRET_LIMITS = Object.freeze({
+    /**
+     * Characters of a name (64, at least 1), each one of `a-z`, `0-9`, `.`,
+     * `_` and `-`.
+     */
+    nameChars: 64,
+    /** UTF-8 bytes of a value (1024, at least 1; no NUL character). */
+    valueBytes: 1024,
+    /** Different names one plugin may have stored at the same time (256). */
+    names: 256,
+});
+const SECRET = new RegExp(`^[a-z0-9._-]{1,${SECRET_LIMITS.nameChars}}$`);
 export const secrets = (scope) => {
     const named = (name) => {
         if (!scope.runtime.can("secrets"))
             throw failure("capability", "secrets must be declared in manifest");
         if (typeof name !== "string" || !SECRET.test(name))
-            throw failure("invalid", "secret names are 1–64 of a-z, 0-9, ., _ and -");
+            throw failure("invalid", `secret names are 1–${SECRET_LIMITS.nameChars} of a-z, 0-9, ., _ and -`);
         return name;
     };
     return {
@@ -307,8 +332,8 @@ export const secrets = (scope) => {
             if (typeof value !== "string" ||
                 !value ||
                 value.includes("\0") ||
-                Buffer.byteLength(value) > 1024)
-                throw failure("invalid", "secret values are 1–1024 bytes of text; delete() removes one");
+                Buffer.byteLength(value) > SECRET_LIMITS.valueBytes)
+                throw failure("invalid", `secret values are 1–${SECRET_LIMITS.valueBytes} bytes of text; delete() removes one`);
             await scope.runtime.host.secrets.set(named(name), value);
         },
         delete: async (name) => scope.runtime.host.secrets.delete(named(name)),

package/dist/plugin/testing.d.ts

@@ -2,7 +2,14 @@ import type { Server } from "node:net";
 import { HostError } from "../wire.ts";
 import type { PackageManifest, PackageSource } from "./types.ts";
 import type { Json, LayoutSlot, LocalServices, PlaybackStats, Transport, WireSystemInfo } from "../wire.ts";
-import { COMMAND_LIMITS, MENU_IDS } from "../commands.ts";
+import { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS } from "../commands.ts";
+import type { BuiltinCommand, BuiltinSubmenu } from "../commands.ts";
+import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.ts";
+import type { CapabilityInfo } from "../capabilities.ts";
+import { OSD_LIMITS } from "./osd.ts";
+import { SECRET_LIMITS } from "./services.ts";
+import { BINDING_INPUTS } from "./bindings.ts";
+import { THEME_PALETTES } from "../palettes.ts";
 import { UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
@@ -15,6 +22,22 @@ import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
 export { HostError };
 /** The player's command caps, which the test host enforces as well. */
 export { COMMAND_LIMITS, MENU_IDS };
+/** The submenus of the player's built-in plugins, by key path. */
+export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS };
+export type { BuiltinCommand, BuiltinSubmenu };
+/** The manifest capabilities: what each opens and how the store shows it. */
+export { CAPABILITY_INFO };
+export type { CapabilityInfo };
+/** The longest message a plugin may send the player. */
+export { MESSAGE_LIMIT };
+/** The player's limits on the on-screen display. */
+export { OSD_LIMITS };
+/** The player's limits on stored secrets. */
+export { SECRET_LIMITS };
+/** The names bindings are made of. */
+export { BINDING_INPUTS };
+/** The colours of the player's palettes, by `Theme` token. */
+export { THEME_PALETTES };
 /** The player's property value limits, which the test host enforces as well. */
 export { UI_VALUE_LIMITS };
 /**

package/dist/plugin/testing.js

@@ -65,7 +65,12 @@ import { tmpdir } from "node:os";
 import { extname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HostError } from "../wire.js";
-import { COMMAND_LIMITS, MENU_IDS } from "../commands.js";
+import { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "../commands.js";
+import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
+import { OSD_LIMITS } from "./osd.js";
+import { SECRET_LIMITS } from "./services.js";
+import { BINDING_INPUTS } from "./bindings.js";
+import { THEME_PALETTES } from "../palettes.js";
 import { UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
 import { nodeProblem } from "../processing.js";
 import { RENDER_DEFAULTS, renderProblem, VIEW_DEFAULTS, viewProblem, } from "./view.js";
@@ -76,6 +81,20 @@ import { Catalog, format as formatTemplate, HOST_GROUPS, HOST_ZH_HANS, LOCALES,
 export { HostError };
 /** The player's command caps, which the test host enforces as well. */
 export { COMMAND_LIMITS, MENU_IDS };
+/** The submenus of the player's built-in plugins, by key path. */
+export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS };
+/** The manifest capabilities: what each opens and how the store shows it. */
+export { CAPABILITY_INFO };
+/** The longest message a plugin may send the player. */
+export { MESSAGE_LIMIT };
+/** The player's limits on the on-screen display. */
+export { OSD_LIMITS };
+/** The player's limits on stored secrets. */
+export { SECRET_LIMITS };
+/** The names bindings are made of. */
+export { BINDING_INPUTS };
+/** The colours of the player's palettes, by `Theme` token. */
+export { THEME_PALETTES };
 /** The player's property value limits, which the test host enforces as well. */
 export { UI_VALUE_LIMITS };
 /**
@@ -2545,8 +2564,8 @@ export class TestHost {
         },
         "osd.show": (p) => {
             const text = this.#shown(p.text, p.args, "text").replace(/[\n\r]/g, " ");
-            if (!text.trim() || [...text].length > 200)
-                throw new HostError("invalid", "osd text needs 1..200 characters");
+            if (!text.trim() || [...text].length > OSD_LIMITS.messageChars)
+                throw new HostError("invalid", `osd text needs 1..${OSD_LIMITS.messageChars} characters`);
             this.osd.push(text);
         },
         "osd.panel": (p) => {
@@ -2554,10 +2573,20 @@ export class TestHost {
                 return void (this.osdPanel = null);
             const max = p.maxColumns;
             if (max !== undefined &&
-                !(Number.isInteger(max) && Number(max) >= 8 && Number(max) <= 1000))
-                throw new HostError("invalid", "maxColumns is an integer from 8 to 1000");
-            const text = this.#shown(p.text, p.args, "text");
-            this.osdPanel = max === undefined ? text : fitColumns(text, Number(max));
+                !(Number.isInteger(max) &&
+                    Number(max) >= OSD_LIMITS.minColumns &&
+                    Number(max) <= OSD_LIMITS.maxColumns))
+                throw new HostError("invalid", `maxColumns is an integer from ${OSD_LIMITS.minColumns} to ${OSD_LIMITS.maxColumns}`);
+            const shown = this.#shown(p.text, p.args, "text");
+            const text = max === undefined ? shown : fitColumns(shown, Number(max));
+            // As the player: \n separates lines, a trailing one ends the last.
+            const lines = text.split("\n");
+            if (text.endsWith("\n"))
+                lines.pop();
+            if (Buffer.byteLength(text) > OSD_LIMITS.panelBytes ||
+                lines.length > OSD_LIMITS.panelLines)
+                throw new HostError("invalid", `osd panel allows ${OSD_LIMITS.panelLines} lines, ${OSD_LIMITS.panelBytes} bytes`);
+            this.osdPanel = text;
         },
         "playback.stats": () => this.stats,
         "audio.addTrack": (p) => {

package/dist/plugin/types.d.ts

@@ -320,16 +320,19 @@ export interface Plugin extends Scope {
     /** The manifest id, e.g. `"community.bookmark"`. */
     readonly id: string;
     /**
-     * A writable directory for this plugin's own files (settings, remembered
-     * folders). Kept across restarts, disabling and upgrades. Write files atomically: to a temporary name, then rename.
-     * Throws `unavailable` when the player provided none.
-     *
-     * Location: `~/Library/Application Support/Vestra/plugin-data/<id>/` on
-     * macOS, `%APPDATA%\Vestra\plugin-data\<id>\` on Windows (the environment
-     * variable `VESTRA_PLUGIN_DATA` moves the root). Another plugin's data
-     * directory is `join(dirname(plugin.dataDirectory), id)`. It is deleted
-     * only by `packages.uninstall(id, { removeData: true })`. No capability.
-     * For JSON settings prefer {@link Scope.storage}.
+     * A writable directory for this plugin's own files (settings, caches,
+     * remembered folders), created by the player before it starts the plugin.
+     * Each installation has its own directory (player 0.2.0): it is kept across
+     * restarts, disabling, upgrades and rollbacks, and a reinstall of the same
+     * id from a different source gets a new, empty one. It is deleted only by
+     * `packages.uninstall(id, { removeData: true })`. No capability.
+     *
+     * The path's format is not part of the API: do not derive another
+     * plugin's directory from it (a plugin manager reads
+     * {@link PluginInfo.dataDirectory}). Write files atomically (to a
+     * temporary name, then rename); for JSON settings prefer
+     * {@link Scope.storage}. Throws `unavailable` when the player provided
+     * none. See [How a plugin runs](../../docs/concepts/plugins.md#the-data-directory).
      */
     readonly dataDirectory: string;
 }
@@ -388,9 +391,10 @@ export type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "sc
  * item never moves the player's menu. Directly inside a built-in menu,
  * `order` 0 (the default) sorts after every other order: an item without
  * `order` goes at the end, after the player's own items (which all use 100
- * or more). Give a positive order to sit between them (the player's orders
- * are listed in its menu table, doc/product/menus.md), or a negative one to
- * come first. Deeper levels (a plugin's own submenu) have no such rule.
+ * or more). Give a positive order to sit between them (the player's items
+ * in menu order are in
+ * [Built-in commands](../../docs/reference/commands.md#built-in-commands)),
+ * or a negative one to come first. Deeper levels (a plugin's own submenu) have no such rule.
  * Players before 0.3.0 place every submenu at its smallest order, so there
  * an item without `order` moves the whole menu to the top; to avoid that,
  * give it an order in the menu's range (Video: 400–499).
@@ -471,8 +475,8 @@ export interface CommandOptions {
      *
      * Platforms: on macOS `Ctrl+X` fires for both ⌃X and ⌘X while `Cmd+X`
      * means ⌘X only; on Windows `Cmd` is the Windows logo key, so write
-     * `Ctrl+…` for bindings that work on both. Avoid keys the system takes
-     * first (⌃F1–⌃F8, ⌃Arrow keys, ⌘Tab on macOS).
+     * `Ctrl+…` for bindings that work on both. Avoid the
+     * [keys the system takes first](../../docs/reference/commands.md#keys-the-system-takes-first).
      *
      * Conflicts are not errors: the user's overrides win, then the player's
      * own commands, then the plugin loaded first; a shadowed binding takes
@@ -812,6 +816,15 @@ export interface Ui {
      * The text is at most 256 KB; very long documents are cut off after 4000
      * blocks.
      *
+     * `MarkdownView` scrolls one document. `MarkdownBlocks` (SDK 1.5.4, players
+     * after 0.4.0) draws one without scrolling, as tall as its content, for a
+     * layout of your own or a `ListView` row. For a list of documents, write
+     * the whole list with one document per row: the player parses only the
+     * documents that changed and updates the list in place (rows added or
+     * removed at the end, a growing document's changed blocks), so re-sending
+     * the list on every streamed chunk keeps the scroll position and costs
+     * little.
+     *
      * @capability None.
      * @player 0.2.0 (set `"minPlayerVersion": "0.2.0"` in the manifest)
      *
@@ -826,6 +839,44 @@ export interface Ui {
      *   `base` is neither an `http(s):` address nor an absolute path.
      * @throws `unsupported` (rejects) The player is older than 0.2.0.
      *
+     * @example A chat: one Markdown document per row, with Copy buttons
+     * `ui/chat.slint`:
+     *
+     * ```slint
+     * import { ListView } from "std-widgets.slint";
+     * import { MarkdownBlocks, MarkdownBlock } from "@vestra/markdown.slint";
+     * export struct Message { id: string, role: string, body: [MarkdownBlock] }
+     * export component Chat inherits Window {
+     *     in property <[Message]> messages;
+     *     callback copy-code(string);
+     *     ListView {
+     *         for message in root.messages: VerticalLayout {
+     *             padding: 8px;
+     *             MarkdownBlocks {
+     *                 blocks: message.body;
+     *                 code-copy: true;
+     *                 copy-code(code) => { root.copy-code(code); }
+     *             }
+     *         }
+     *     }
+     * }
+     * ```
+     *
+     * ```ts
+     * const chat = plugin.windows.create("ui/chat.slint");
+     * const history: { id: string; role: string; text: string }[] = [];
+     * chat.on("copyCode", (code: string) => plugin.clipboard.writeText(code));
+     * async function render() {
+     *   const messages = [];
+     *   for (const { id, role, text } of history)
+     *     messages.push({ id, role, body: await plugin.ui.markdown(text) });
+     *   chat.set({ messages });
+     * }
+     * history.push({ id: "1", role: "user", text: "Show me `ls`." });
+     * await render();
+     * await chat.show();
+     * ```
+     *
      * @example Show a README from the web
      * ```ts
      * const readmeUrl = "https://example.com/plugin/README.md";
@@ -1029,8 +1080,8 @@ export interface View {
  *    {@link View.bind} or {@link View.set}.
  * 3. {@link Window.show} opens the window with those properties.
  *    {@link Window.hide} hides it and keeps its state.
- * 4. {@link Window.close}, or the user (title-bar button; ⌘W on macOS,
- *    Ctrl+W or Ctrl+F4 on Windows), destroys the window instance; only the
+ * 4. {@link Window.close}, or the user (title-bar button or the
+ *    [standard close keys](../../docs/reference/commands.md#keys-the-system-takes-first)), destroys the window instance; only the
  *    user's close calls {@link Window.onClose}. The handle stays usable: the
  *    next `show()` opens a fresh instance with the current properties.
  * 5. `dispose()`, disposing the owning scope or the plugin stopping closes
@@ -1184,8 +1235,8 @@ export interface Window extends View, Disposable {
      * Run code when the user closes the window.
      *
      * @remarks
-     * Called for the title-bar close button and the standard close keys (⌘W
-     * on macOS, Ctrl+W or Ctrl+F4 on Windows). When it runs, the window
+     * Called for the title-bar close button and the
+     * [standard close keys](../../docs/reference/commands.md#keys-the-system-takes-first). When it runs, the window
      * instance is gone and {@link Window.opened} is already `false`; a later
      * `show()` opens a fresh one. It is not called for the plugin's own
      * {@link Window.close} or `dispose()`, nor when the plugin stops. Errors
@@ -1514,8 +1565,8 @@ export interface PanelSlot {
  * Detached, the sidebar panel is shown in a separate window (300×408 by
  * default, at least 300×250) with the panel's `title`. The plugin's
  * properties and callbacks stay the same, but the window holds a new
- * instance of the component. Closing the floating window (its close button,
- * ⌘W, Ctrl+W, Ctrl+F4) is the same as `setVisible(false)`.
+ * instance of the component. Closing the floating window (its close button
+ * or the [standard close keys](../../docs/reference/commands.md#keys-the-system-takes-first)) is the same as `setVisible(false)`.
  *
  * @capability ui.mount
  *
@@ -3714,8 +3765,8 @@ export interface Host {
  * {@link Osd.panel}.
  *
  * @remarks
- * The block sits under the OSD message line, on a translucent black
- * background, and takes no input. Its font scales with the video area. When
+ * The block sits under the OSD message line, on a translucent dark plate
+ * (see {@link Osd} for sizes), and takes no input. When
  * several plugins have one, they are stacked from top to bottom. `dispose()`,
  * disposing the scope or stopping the plugin removes it.
  *
@@ -3789,8 +3840,25 @@ export interface OsdPanelOptions {
  * ({@link Osd.show}) is one line at the top left of the video that
  * disappears after 2 seconds; a newer message, from any plugin, replaces it.
  * The information block ({@link Osd.panel}) stays until the plugin changes
- * or removes it. Both are white text with a dark outline whose size follows
- * the height of the video area.
+ * or removes it.
+ *
+ * How the player draws them (a player before 0.4.0 drew bold white text
+ * with a black outline instead):
+ *
+ * - **Message**: white text on a translucent dark plate with rounded
+ *   corners and a gradient line along its bottom edge, 10px from the
+ *   video area's left and top edges.
+ * - **Font size** follows the video area: 3 % of its height, rounded and
+ *   clamped to 12–48px (about 18px in the default window, 32px in
+ *   fullscreen at 1080 pixels high). The plate's padding and corners scale
+ *   with it.
+ * - **Information block**: 4px below the message plate, on the same kind of
+ *   plate; its font scales in proportion (11px when the message is 16px),
+ *   clamped to 9–28px.
+ *
+ * How long a text may be is in
+ * [Limits: on-screen display](../../docs/reference/limits.md#on-screen-display)
+ * ({@link "@vestra-player/sdk/testing"!OSD_LIMITS | OSD_LIMITS}).
  *
  * @capability ui.osd
  *