@vestra-player/sdk 1.5.13 → 1.5.15

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.13: full reference
+# @vestra-player/sdk 1.5.15: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -10,15 +10,15 @@ Limits: 160 commands per plugin and 1024 in the player (`limit`); menu ids for t
 
 This guide walks through a complete Vestra Player plugin: the files it is made of, the manifest, a first command, a window, tests, and packaging. The API reference is split into @vestra-player/sdk (the plugin API) and @vestra-player/sdk/testing (the test host); start from Plugin and Scope.
 
-### How plugins run
+#### How plugins run
 
-- Each plugin runs in its own Node.js process (Node.js 26, which the player ships) started by the player. It can use the Node standard library, the file system, the network and npm packages.
-- The player loads the entry module and calls its **default export** `activate(plugin)`. The `plugin` object is created by the player; the plugin imports the SDK **as types only**, so a built plugin contains nothing but its own code.
-- Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle owned by `plugin` or a child scope, and is released automatically when the plugin stops. There is no cleanup function to return.
-- Plugins are trusted code. Manifest capabilities are a contract that the player enforces per call (a missing one fails with `code: "capability"`), not a security sandbox.
-- The API is the same on macOS and Windows. A feature a system cannot provide fails with `unsupported`; each method documents its platform differences.
+- Each plugin runs in its own Node.js process (Node.js 26, which the player ships). It can use the Node standard library, the file system, the network and npm packages.
+- The player loads the entry module and calls its **default export** `activate(plugin)`. The plugin imports the SDK **as types only**, so a built plugin contains nothing but its own code.
+- Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. There is no cleanup function to return.
 
-### Rules for plugins
+How a plugin runs explains the process, activation, handles, the update pass and failures in full.
+
+#### Rules for plugins
 
 Every plugin, in the official plugin repository or not, follows these rules. They keep plugins independent of each other and portable.
 
@@ -28,7 +28,7 @@ Every plugin, in the official plugin repository or not, follows these rules. The
 - **macOS and Windows.** The same code runs on both: build paths with `node:path`, write package paths with `/`, and handle `unsupported` where a method documents a platform difference.
 - **Your own id.** `<owner>.<name>`, where the owner is your GitHub user or organization. `vestra` and `vestra.*` are reserved for the plugins built into the player.
 
-### Install
+#### Install
 
 ```sh
 mkdir my-plugin && cd my-plugin
@@ -39,7 +39,7 @@ npm i -D @vestra-player/sdk
 
 The package brings its own TypeScript 5.x and `@types/node`, and the `vestra-plugin` command line tool.
 
-### Files
+#### Files
 
 ```text
 my-plugin/
@@ -65,7 +65,7 @@ my-plugin/
 }
 ```
 
-### The manifest
+#### The manifest
 
 ```json
 {
@@ -77,84 +77,25 @@ my-plugin/
 }
 ```
 
-| Field              | Rule                                                                                                                                                                                                         |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`               | Non-empty, globally unique identifier; use `author.plugin`.                                                                                                                                                  |
-| `version`          | Three non-negative integers `x.y.z`. `vestra-plugin build` writes it into `dist/manifest.json`.                                                                                                              |
-| `apiVersion`       | Always `"vestra/1"` for this major version of the SDK.                                                                                                                                                       |
-| `entry`            | Relative path inside the package: `.ts` during development, `.js` after building.                                                                                                                            |
-| `capabilities`     | Only names from the table below.                                                                                                                                                                             |
-| `minPlayerVersion` | Optional `x.y.z`: the oldest player that can load the plugin. Older players refuse it with `versionMismatch` ("requires Vestra Player ≥ x.y.z"). Set it when you use API added after SDK 1.0 (see Versions). |
+- `id` is your plugin's identifier: `<owner>.<name>`, ASCII letters, digits, `.`, `-` and `_`.
+- `version` is `x.y.z`; `vestra-plugin build` writes it into the package.
+- `apiVersion` is always `"vestra/1"` for this major version of the SDK.
+- `entry` is the entry module: `.ts` while you develop, `.js` after building.
+- `capabilities` lists what the plugin may do. A call to a member whose capability is missing fails with `code: "capability"`.
 
-Optional display fields (player 0.2.0), shown by the plugin store and plugin manager:
+Optional display fields (`name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`) are shown by the plugin store and the plugin manager, and `minPlayerVersion` names the oldest player that can load the plugin. Every field with its exact rules is in Manifest.
 
-| Field         | Rule                                                                                          |
-| ------------- | --------------------------------------------------------------------------------------------- |
-| `name`        | 1–64 characters, one line.                                                                    |
-| `author`      | 1–64 characters, one line.                                                                    |
-| `punchline`   | One-line summary, 1–120 characters.                                                           |
-| `description` | Plain text, 1–2000 characters; line breaks allowed.                                           |
-| `tags`        | Up to 8 tags, 1–24 characters each, unique ignoring case.                                     |
-| `icon`        | Package path of a PNG or JPEG, at most 512 KB and 1024 pixels per side (256×256 recommended). |
-| `readme`      | Package path of a UTF-8 `.md` file (≤ 256 KB). Default: `README.md` when present.             |
-| `changelog`   | Same, default `CHANGELOG.md` when present.                                                    |
-| `sourceUrl`   | `https:` address of the source code.                                                          |
-| `license`     | 1–64 characters, preferably an SPDX expression such as `MIT`.                                 |
+The capabilities you need first:
 
-A manifest with every field. `id`, `apiVersion`, `entry` and `capabilities` are required; without `version`, `vestra-plugin build` takes it from `--version` or `package.json`.
+| Capability      | Opens                                                                                              |
+| --------------- | -------------------------------------------------------------------------------------------------- |
+| `commands`      | `plugin.commands.add` (menu items and key bindings) and `plugin.host.run`                          |
+| `ui.window`     | `plugin.windows.create` (tool windows)                                                             |
+| `playback.read` | reading `plugin.player.state` (what is playing, the position), `stats`, `chapters`, timeline marks |
 
-```json
-{
-  "id": "me.hello",
-  "version": "0.1.0",
-  "apiVersion": "vestra/1",
-  "entry": "main.ts",
-  "capabilities": ["commands", "ui.osd"],
-  "minPlayerVersion": "0.4.1",
-  "name": "Hello",
-  "author": "Me",
-  "punchline": "Says hello from the Tools menu.",
-  "description": "A first plugin.\nIt adds Tools ▸ Hello, which shows an on-screen message.",
-  "tags": ["example"],
-  "icon": "assets/icon.png",
-  "readme": "README.md",
-  "changelog": "CHANGELOG.md",
-  "sourceUrl": "https://github.com/me/hello",
-  "license": "MIT"
-}
-```
-
-Unknown fields, unknown capabilities and paths that leave the package directory (including through symbolic links) are rejected. The id's characters are ASCII letters, digits, `.`, `-` and `_`; the official plugin repository additionally requires `<GitHub user or organization>.<plugin name>`. The `vestra.` prefix (and the id `vestra`, in any case) is reserved for the plugins built into the player: from player 0.4.1 the player refuses to install such a package (`reserved`). Every other plugin is a third-party plugin, including those hosted in the official repository.
-
-| Capability                             | Opens                                                                                                   |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `commands`                             | `commands.add`, `host.run`                                                                              |
-| `ui.window`                            | `windows.create`                                                                                        |
-| `ui.mount`                             | `panels.mount`, `panels.bottom` / `.sidebar` / `.backdrop`                                              |
-| `ui.dialog`                            | `dialogs.*`                                                                                             |
-| `ui.osd`                               | `osd.show`, `osd.panel`                                                                                 |
-| `ui.drop`                              | `drops.provide`, `Panel.onDrop`                                                                         |
-| `ui.theme`                             | `appearance.set`                                                                                        |
-| `ui.settings`                          | `settings.page`, `settings.show`                                                                        |
-| `playback.read`                        | reading `player.state` at start, `refresh`, `stats`, `chapters`, `audioDevices`, `timeline.marks`       |
-| `events`                               | live `player.state` / `onChange`, panel visibility, subtitle and window updates                         |
-| `playback.control`                     | `player.open`, `setPaused`, `seek`, `setRate`, … and `power.preventSleep`                               |
-| `producer.av`                          | `player.openStream` (with `playback.control`: the stream becomes the player's source)                   |
-| `processing.video`                     | `video.filter` (with `playback.read` and `events`), `video.view`, `video.render` (with `playback.read`) |
-| `processing.audio`                     | `audio.filter` (with `playback.read` and `events`)                                                      |
-| `subtitles.read` / `subtitles.control` | reading / changing subtitles                                                                            |
-| `media.read` / `media.control`         | `media.capture`, snapshot exports                                                                       |
-| `source.resolve`                       | `resolvers.add`                                                                                         |
-| `plugins.manage`                       | `packages.validate`, `rollback`, `setEnabled`, `uninstall`                                              |
-| `clipboard`                            | `clipboard.*`                                                                                           |
-| `window.control`                       | `window.setVideoArea`, `setAlwaysOnTop`, `setCursorAutoHide`, `setPictureInPicture`                     |
-| `bindings.manage`                      | `bindings.*`                                                                                            |
-| `timeline.marks`                       | `timeline.layer()`                                                                                      |
-| `secrets`                              | `secrets.*`                                                                                             |
-
-No capability is needed for `tools`, `storage`, `system`, `ui.image`, `plugin.app`, reading `window.state` and `appearance.theme`, and `packages.list`.
-
-### A first plugin
+The plugin on this page also uses `ui.osd` (on-screen messages), `events` (follow playback changes as they happen) and `playback.control` (seeking). Every capability, with the members it opens and the capabilities they also need, is in Capabilities.
+
+#### A first plugin
 
 ```ts
 // main.ts
@@ -176,12 +117,12 @@ export default async function activate(plugin: Plugin) {
 }
 ```
 
-- `path` is the menu path, matched by exact titles. "Tools" is a new top-level menu of this plugin. To put an item into one of the player's own menus, start the path with its id instead of its title, which depends on the player's language: `["@video", "Blur"]` (also `@open`, `@playback`, `@subtitles`, `@audio`, `@screen`, `@settings`; player 0.3.0).
+- `path` is the menu path in English; paths merge by these words in every interface language. "Tools" is a new top-level menu of this plugin. To put an item into one of the player's own menus, start the path with its id, such as `["@video", "Blur"]` (Built-in menus).
 - `enabled` is a function: the SDK re-evaluates it after every handler and every state change it receives, and sends only changes. This needs `events` to follow outside changes.
 - `run` may return a promise. Errors thrown or rejected there go to `plugin.onError`, then to the plugin log.
 - Commands are registered in the background; activation succeeds once every registration made during `activate` succeeded.
 
-### A window
+#### A window
 
 User interfaces are Slint files in the package. The plugin writes properties and handles callbacks; property and callback names may be written in camelCase and are converted to Slint's kebab-case.
 
@@ -223,7 +164,7 @@ This needs `ui.window`, `commands`, `playback.read`, `events` and `playback.cont
 
 `@vestra/theme.slint` and `@vestra/widgets.slint` come from the player at run time. For editor support, point the Slint language server's library path `vestra` at `node_modules/@vestra-player/sdk/slint/vestra` (a read-only copy that matches the player).
 
-### Testing
+#### Testing
 
 `@vestra-player/sdk/testing` runs a plugin against `TestHost`, an in-memory player that speaks the real protocol, so the SDK's own logic runs unchanged. There is no decoding, Slint or native window.
 
@@ -246,11 +187,11 @@ test("shows the position", async () => {
 });
 ```
 
-Useful controls: `host.command(id).run()`, `host.press("Ctrl+Alt+W")`, `host.window(id).emit(callback, ...args)` and `.props`, `host.openElsewhere(path)`, `host.handle(method, fn)` to inject failures (throw a `HostError`), `host.settle()` to wait until the plugin's host calls are answered (it does not wait for the plugin's own file reads or child processes: poll the result you assert on, see `settle`). See TestHost.
+Useful controls: `host.command(id).run()`, `host.press("Ctrl+Alt+W")`, `host.window(id).emit(callback, ...args)` and `.props`, `host.openElsewhere(path)`, `host.handle(method, fn)` to inject failures (throw a `HostError`), `host.settle()` to wait until the plugin's host calls are answered (it does not wait for the plugin's own file reads or child processes: poll the result you assert on, see `settle`). See TestHost and Test a plugin.
 
 Run them with `npm test` (`vestra-plugin test`, which is `node --test tests/*.test.{ts,mjs}`).
 
-### Check, run, build and pack
+#### Check, run, build and pack
 
 ```text
 vestra-plugin check [plugin-dir...]
@@ -259,24 +200,466 @@ vestra-plugin build [plugin-dir...] [--version x.y.z]
 vestra-plugin pack  [plugin-dir...] [--version x.y.z] [--out dir]
 ```
 
-- `check`: checks the manifest (every rule above), then a strict type check of the plugin's `.ts` files and `tests/`. It extends the nearest `tsconfig.json` at or above the plugin directory, else built-in strict settings. Hints that do not fail the check (such as an id without an owner prefix) are printed.
-- `build`: checks, then writes `dist/`: `.ts` files with types stripped (relative imports rewritten to `.js`), `.slint`, `.mjs` and data files copied, the manifest's `icon`, `readme` and `changelog` (and `README.md` / `CHANGELOG.md` when present) copied, `dist/manifest.json` with the version (from `--version`, else the manifest, else `package.json`). Tests, `node_modules/`, other Markdown and `package*.json` are left out. A runtime import of `@vestra-player/sdk` fails the build.
-- `pack`: builds, then packs `dist/` as `<id>-<version>.vxp` (a zip with `manifest.json` at its root; the same input gives the same bytes) and prints its size and sha256. This is the file users install and repositories list.
-- Runtime npm dependencies must be bundled: set `"vestra": { "bundle": true }` (or `{ "bundle": { "external": [...] } }`) in the plugin's `package.json` and add `esbuild` as a dev dependency. `"vestra": { "assets": ["vendor"] }` copies extra files verbatim.
+- `check` checks the manifest, then type checks the plugin's `.ts` files and `tests/` strictly.
+- `build` checks, then writes `dist/`: the code with types stripped, the Slint and data files, and `dist/manifest.json` with the version. A runtime import of `@vestra-player/sdk` fails the build.
+- `pack` builds, then packs `dist/` as `<id>-<version>.vxp`, the file users install and the plugin store lists.
+
+What `build` puts into the package, how to bundle npm dependencies and the translation commands are in Command line.
 
 During development no build is needed: start the player with `--plugin <plugin-dir>` (repeatable) to run `main.ts` directly.
 
-### Versions
+#### Versions
+
+Every 1.x release of the SDK implements the plugin API `vestra/1`; minor releases only add to it, and a breaking change gets a new `apiVersion` and a new major version. Some additions need a newer player: when you use one, set `minPlayerVersion` to the version it names. Player versions lists which API needs which player.
+
+## Concept: How a plugin runs
+
+Every other concept page builds on this one. It explains what the player does with a plugin from the moment it starts it until it stops it: the process the plugin runs in, the `activate` function, the handles everything is made of, the update pass that keeps the player in step with the plugin's state, what happens when the plugin stops, where it keeps its files, and how failures reach it.
+
+It assumes you have written a first plugin (Getting started). For each type's members, follow the links into the API reference.
+
+#### The plugin process
+
+- **One Node.js process per plugin.** The player starts each plugin in a Node.js 26 process of its own (the installed player ships that Node.js). The plugin can use the Node standard library, the file system, the network and npm packages. A crash or a busy loop in one plugin does not stop the player or other plugins.
+- **No web storage.** The player starts Node with `--no-experimental-webstorage`, so `localStorage` and `sessionStorage` do not exist. Keep settings with plugin.storage or in your own files in the data directory.
+- **Trusted code.** Manifest capabilities are a contract the player checks on every call (a missing one fails with `code: "capability"`), not a sandbox: the process has the user's file and network access. The full list of capabilities and the API each one opens is in Reference: capabilities.
+- **One API on every system.** The same plugin runs on macOS and Windows. Something a system cannot do fails with `unsupported`; the differences are collected in Reference: platforms.
+- **Types only.** The plugin imports `@vestra-player/sdk` with `import type`. The `plugin` object it receives is built by the player's copy of the SDK, so a built plugin contains only its own code and keeps working with the SDK version the player ships.
+
+The plugin and the player talk over the process's standard input and output. The SDK hides that protocol completely: a plugin only ever sees handles, promises and listeners.
+
+#### Activation
+
+The entry module must **default-export** `activate` (a named export is refused):
+
+```ts nocheck
+import type { Plugin } from "@vestra-player/sdk";
+
+export default async function activate(plugin: Plugin) {
+  // create handles: commands, windows, panels, filters, listeners…
+}
+```
+
+When the player starts the plugin:
+
+1. It starts the process, and the SDK loads the entry module.
+2. The SDK reads the initial state the plugin may see (the playback state with `playback.read`, the main window and timeline state) and, with `events`, subscribes to changes.
+3. It calls `activate(plugin)`.
+4. It waits until every registration started during activation has succeeded: commands, panels, settings pages, resolvers, subscriptions. Then it reports the plugin ready.
+
+You do not need to `await` those registrations. `commands.add`, `panels.mount` and `resolvers.add` return their handle at once and register in the background; their `ready` promise is there for the rare case that you want to wait. **Activation fails** when `activate` throws or rejects, or when one of those registrations fails. A registration made later, after activation, cannot fail activation any more: its failure goes to `onError`.
+
+Some refusals are deliberately not failures, because they depend on which other plugins are installed: a bottom bar or backdrop that another plugin's panel already holds, the next/previous sequence that another plugin provides, a file type or web host that another plugin already resolves. The plugin keeps running without that part, the player tells the user, and the plugin manager shows it as a warning (PluginInfo.warnings). The player's built-in plugins register first, so they win these contests at start-up.
+
+#### Handles and scopes
+
+Everything a plugin creates is a **handle**: an object that stands for one resource, carries its operations and its listeners, and implements Disposable. A command, a window, a panel, a filter chain, a snapshot, an export job, a resolver, a generated stream and every listener (`onChange`, `bind`, `on`…) are handles.
+
+```text
+plugin (root scope)
+ ├─ command "open-inspector"
+ ├─ window "inspector"            ← view.on / view.bind listeners belong to it
+ ├─ video filter "picture"
+ └─ child scope "tracks"          ← plugin.scope()
+     ├─ command "track.0"
+     └─ command "track.1"
+```
+
+- Every handle belongs to the Scope it was created through. Plugin is the root scope; plugin.scope() makes a child with exactly the same modules.
+- Disposing a scope disposes its handles and deeper scopes in reverse creation order. Disposing twice is harmless, and `dispose()` never rejects (a failure is only logged).
+- **Child scopes are for things that come and go together.** A menu that lists the current tracks, a window and the timer that feeds it, a feature the user can switch off: create them in a child scope and dispose the scope to remove them all, then build a new one. Titles and menu paths cannot change in place, so this is also how a changing menu is rebuilt (see the example on Scope).
+- add(handle) hands an existing handle to another scope; onDispose(cleanup) runs your own cleanup (a `clearInterval`, closing a socket) with the scope.
+- What disposing does depends on the handle (a window closes, a filter chain is withdrawn, a stream stops…); Disposable lists it. The one exception is Media: disposing its scope does not close what the plugin opened, because the user is watching it. Call `media.close()` when you mean it.
+
+There is no cleanup function to return from `activate`. Because every resource is a handle owned by a scope, stopping the plugin releases everything.
+
+#### The update pass
+
+A plugin's state is plain variables. The SDK keeps the player in step with it through **bindings** and the **update pass**:
+
+- A binding is a function the SDK calls to get a current value: view.bind(() => props) for a window, panel or settings page, and the function form of a command's `enabled`, `checked`, `busy` and `reason` (Bindable).
+- In an update pass the SDK calls every binding of the plugin, compares each result with the value it last sent, and sends only what changed.
+
+Update passes run:
+
+- after every handler the SDK calls returns (a command's `run`, a view callback, an `onChange`, `onStatus`, `onEnd` or `onStop` listener), and again when the promise it returned settles;
+- after the player, subtitle, panel position, filter or export state changes;
+- when the plugin calls plugin.update().
+
+Several requests within one microtask are merged into one pass, and every target has at most one write in flight: values that change meanwhile are merged into the next write. A binding that changes 60 times a second therefore costs one write per round trip, never a growing queue.
+
+One click, end to end (a bookmark window; the video is at 42 s):
+
+```text
+user clicks "Mark this position"
+                    ─▶  Slint: clicked => { root.mark(); }
+                    ─▶  the player forwards the callback to the plugin
+                    ─▶  window.on("mark") handler runs: mark = 42
+handler returns     ─▶  update pass: every binding is evaluated
+                          label   "Bookmark: 42.0 s"   changed  → sent
+                          canMark true                 same     → not sent
+                          canJump true                 changed  → sent
+                    ─▶  the label changes; "Jump to bookmark" is enabled
+```
+
+The rule that follows: **state you change outside a handler, or after an `await` inside one, appears only at the next pass.** Changing a variable from your own `setInterval`, a socket callback or the middle of a long task shows nothing until something triggers a pass; call `plugin.update()` after such a change. Keep a slider responsive while dragging shows the pattern; How Slint and TypeScript talk explains `set` versus `bind` for views.
+
+#### Stopping
+
+The player stops a plugin when the user disables or uninstalls it, when it is reloaded or upgraded, and when the player quits.
+
+1. The player first removes everything the plugin owns on its side: menu items, windows, panels, settings pages, filter chains, subtitle layers, snapshots, export jobs, resolvers, generated streams.
+2. The SDK then refuses new requests, fails pending ones with `code: "disabled"` and disposes the root scope. That disposal only cleans up locally (timers, abort signals, sockets): the player-side resources are already gone.
+3. A process that has not exited 300 ms later is killed.
+
+So `onDispose` cleanup must be quick and must not rely on the player. Media the plugin opened with player.open **keeps playing** after it stops.
+
+#### The data directory
+
+plugin.dataDirectory is a writable directory for the plugin's own files (settings, caches, remembered folders). It needs no capability; the player creates it before it starts the plugin.
+
+- **One directory per installation.** Each fresh installation of a plugin gets its own directory (player 0.2.0). Installing the same id again from the same source is an upgrade and keeps the directory. Installing the same id from a different source, and confirming the replacement, gives the new plugin a new, empty directory; the old one is kept and reconnected if the user goes back to the first source later. A development load (`--plugin`) has a directory of its own.
+- **Kept** when the plugin is disabled, reloaded, upgraded or rolled back. Uninstalling deletes it only when the user asks for that (uninstall with `removeData: true`); otherwise reinstalling from the same source reconnects it.
+- **The path's layout is not part of the API.** Do not derive another plugin's directory from yours; a plugin manager reads it from PluginInfo.dataDirectory.
+- **Write atomically.** Write to a temporary name and rename it, so a player that quits mid-write never leaves half a file; fall back to defaults when a file is missing or unreadable. For JSON settings use plugin.storage.json, which already does this (defaults, debounced atomic writes, a corrupt file moved aside).
+- Reading the property throws `unavailable` when the player could not provide a directory.
+
+Credentials do not belong in files: keep them in the system's secret store with plugin.secrets.
+
+In tests, `TestHost` gives each test an empty temporary directory and deletes it on `stop()`; pass the same `dataDirectory` to two runs to test what survives a restart (Test a plugin).
+
+#### Failures and recovery
+
+Every failure is an ordinary `Error` with a stable `code` (PluginError, which has the table of codes). **Branch on `code`, never on `message`**: the message is for logs and people, and it may change or be translated.
+
+```ts
+try {
+  await plugin.player.seek(30);
+} catch (error) {
+  if ((error as PluginError).code === "stale") return; // the user changed the source meanwhile
+  throw error;
+}
+```
+
+Where a failure goes:
+
+- **A promise you await** rejects, and you handle it like any other error.
+- **A handler the SDK calls** (a command's `run`, a view callback, a listener) that throws or rejects reports to onError of its scope; without a listener, to the parent scope, and finally to the plugin log. So you do not need a `try`/`catch` in every handler; one `onError` that shows the problem is often enough:
+
+  ```ts
+  plugin.onError((error) => {
+    void plugin.osd.show(`Bookmarks: ${error.message}`);
+  });
+  ```
+
+- **A registration after activation** (a command whose `ready` rejects, a property write the player refused) also reports to `onError`.
+- **A promise you forgot to `await`** that rejects is only logged. It never crashes the plugin process.
+- **A lasting target** reports through its status instead: a filter chain, the display layer and the render options are `waiting`, `applying`, `applied` or `failed` (FilterStatus); see Video and audio processing.
+
+Three properties make failures predictable:
+
+- **A refusal did nothing.** A call that fails with a player refusal (`stale`, `busy`, `conflict`, `invalid`, `unavailable`, `unsupported`) was not carried out, so it is safe to show the reason and let the user try again. `stale` in particular means the state your call depended on changed; see conditional controls.
+- **No client-side timeouts.** The player answers every request in order, or stops the plugin. A slow request is logged after 10 seconds, but the SDK keeps waiting for the real answer instead of guessing, so an operation never ends in "maybe".
+- **No blind retries.** The SDK never resends an operation that is not safe to repeat (opening, loading subtitles, starting an export, installing). Only last-write-wins targets such as filter chains are sent again, and only when the SDK knows the earlier write did not take effect. A filter chain that failed with `backend-uncertain` (the player's backend blocked that stage) waits for retry(), the next `set()` or a new source.
+
+## Concept: Commands, menus and key bindings
+
+A plugin offers actions to the user through **commands**. One command can appear as a menu item, run from a key or mouse binding, sit in a panel's context menu and be run by tests, and its state (enabled, checked, busy) is the same everywhere. This page explains that model, how menu paths from all plugins merge into the player's one menu, and how the player decides which command a key press runs.
+
+Where a command should go and how to title it are rules, not concepts: see Guidelines: menus. The names to look up (built-in menu ids, shared menu keys, binding syntax and input names, the player's own commands, keys the system takes first) are in Reference: commands.
+
+#### Commands and state
+
+plugin.commands.add declares a command (capability `commands`) and returns a Command handle:
+
+```ts
+const toggle = plugin.commands.add({
+  id: "toggle-pause",
+  path: ["@playback", "Pause"],
+  bindings: ["Ctrl+P"],
+  enabled: () => plugin.player.state.can.pause,
+  checked: () => plugin.player.state.paused,
+  run: () => plugin.player.setPaused(!plugin.player.state.paused),
+});
+```
+
+- **The id is the command's identity.** It is unique within the plugin; the player knows the command as `<manifest id>/<id>`. The user's own key bindings are stored under that pair, so changing a title or moving the command to another menu keeps them.
+- **`path` puts it in the main menu.** Leave it out for a command that only has bindings or lives in a panel's context menu (Panel.showMenu); it then needs a `title`.
+- **State is declared, not pushed.** `enabled`, `checked`, `busy` and `reason` are values or functions (Bindable). Functions are evaluated in every update pass and sent only when they change, so the menu's check mark follows the player without a listener. Command.set replaces them later.
+- **The player calls `run` only when it can run.** While a command is disabled or busy, neither its menu item nor its binding calls `run`; `reason` tells the user why (it appears in the menu and, for a key press, on the video).
+- **Titles and paths are fixed.** They cannot change in place. A menu that follows changing content (tracks, presets, a radio group) lives in a child scope that is disposed and rebuilt when the content changes; `order` keeps its place (Handles and scopes).
+- Disposing the command removes it from the menu and the binding table; the same id can be added again at once. The number of commands per plugin and per player is limited (Reference: limits); the limit stops runaway menus, so cap menus built from media content (tracks, chapters) yourself.
+
+#### How menu paths merge
+
+The player has **one main menu**, built from the paths of every command of every plugin and of the player itself.
+
+- **Paths are English source text, and they are keys.** `["@video", "Picture", "Brightness…"]` names a place in the menu. Commands of different plugins whose leading segments are the same share that submenu: two plugins that both write `["@playback", "A-B Loop", …]` put their items into one **A-B Loop** submenu.
+- **Each segment is shown translated by the plugin that declared it.** The player looks every segment and the title up in the declaring plugin's catalog (Translate a plugin). A submenu shared by several plugins takes its label from the first command in it. The player's own menus (the seven top-level menus and **Playback ▸ Speed**, **Playback ▸ Seek**) always show the player's words.
+- **Built-in menus** are named by id or by key: `@video` and `Video` are the same menu. The id form is safer, because it fails with `invalid` when misspelled, and players up to 0.4.2 titled their menus in Chinese, where only `@video` reaches the built-in menu. Only the first segment is read as an id.
+- **Shared submenus need a shared key.** Plugins that should meet in one submenu must spell its key identically. The keys already in use (by the player and its built-in plugins) are listed in Reference: commands; reuse one instead of inventing a near-synonym.
+- **A segment with data** (a track number, a count) is a Text from `plugin.i18n.text(…)`: it is shown translated and filled in, and it merges by its English rendering ("Track 2 (opus)").
+
+The same path cannot be registered twice, and a path cannot be both an item and a submenu: the second registration fails with `conflict`.
+
+##### Order and separators
+
+- Siblings sort by `order`, ascending. A submenu sits where the first command inside it sits, and takes that command's `group`. Equal orders sort by plugin id, then declaration order, **never by title** (a translated title would reorder the menu per language).
+- `group` only draws separators: a line appears between neighbours of different groups. To keep a group together, keep its orders contiguous.
+- **Built-in menus keep their place.** The seven built-in top-level menus sit at fixed orders, whatever plugins put inside them. Directly inside a built-in menu, `order` 0 (the default) sorts after every other item, so a plugin item without `order` goes to the end, after the player's own items; a positive order places it between them, a negative one first. Deeper levels have no such rule.
+
+The orders of the player's own items and the recommended top-level ranges are on CommandOptions.
+
+#### How a key finds its command
+
+A binding is a string such as `"Ctrl+Shift+A"`, `"NumpadEnter"` or `"Mouse:WheelUp"` (Reference: commands has the syntax and every input name). When the user presses a key, the player looks for a command in this order:
+
+```text
+key press in the main window or the floating sidebar
+   │  a focused control that uses the key (Space in a text field) keeps it
+   ▼
+this plugin's panel has focus?  ── yes ─▶ its focus: "panel" bindings first
+   ▼
+global bindings
+   │  several commands bind the same input in the same scope:
+   │    1. the user's override   2. the player's own command   3. the plugin loaded first
+   ▼
+winner enabled ──────────────▶ run()   (busy: the key is taken, nothing runs)
+winner disabled ─────────────▶ the next command it shadowed, then the global scope;
+                               none left: its reason on the OSD (key taken),
+                               no reason: the key goes on to the focused control
+```
+
+- **Where bindings apply.** Bindings belong to the main window: they fire while it or the floating sidebar window has focus. They do **not** fire in tool windows or the Options window; keys there are the Slint file's own business (a `FocusScope`, a default button). While a menu or a system dialog is open, bindings pause.
+- **Conflicts are not errors.** A binding that loses is written to the player's log and takes effect by itself when the winner goes away (its plugin stops, the user rebinds it). Tests can check `host.conflicts` (TestHost.conflicts).
+- **A disabled command lets its key go.** This is what makes context-dependent keys work: `Escape` bound to "Leave Fullscreen" does nothing outside fullscreen, so `Escape` reaches the focused control. Give `reason` to a command whose key should still be taken and explained while it is disabled.
+- **`repeat: true`** fires again on the keyboard's auto-repeat while the key is held; without it a binding fires once per press.
+- **Some keys never reach a binding.** The system takes some keys first, and the standard close keys close a tool window, the floating sidebar or the Options window before any binding sees them (in the main window they are ordinary keys). Keys the system takes first lists them; default bindings avoid them.
+
+##### What a key name matches
+
+Key names describe keys, not characters, with two deliberate exceptions:
+
+- **Letters and named keys match the physical key.** `Shift+E` is Shift and E, independent of Caps Lock; `Delete` is the forward-delete key and `Backspace` the ⌫ key; ⌥⌦ is `Alt+Delete`. The numeric keypad has names of its own (`"5"` is only the main 5, `"Numpad5"` only the keypad's).
+- **Symbols match the typed character.** Write `">"`, not `"Shift+."`, and `"!"`, not `"Shift+1"`; `+` is always `Plus`, however the layout produces it.
+- **Option combinations match the physical key**, so `Alt+O` fires for ⌥O although that key types `ø`, and dead keys (⌥E, ⌥N…) fire too. On layouts that need Option to type a symbol (German ⌥5 = ``, ⌥L = `@`), a binding for the typed symbol (`"["`, `"@"`) wins over one for the physical key (`Alt+5`).
+- **`Ctrl` is portable, `Cmd` is not.** On macOS `Ctrl+X` fires for both ⌃X and ⌘X, `Cmd+X` only for ⌘X. On Windows `Cmd` is the Windows logo key, which the system mostly keeps, so write `Ctrl+…` for a binding that works on both systems.
+
+Mouse bindings apply only over the video area. `Mouse:LeftDoubleClick:LeftHalf` and `:RightHalf` win over the plain double click; wheel bindings count accumulated scroll steps. The right button is reserved for the context menu, and a left drag in window mode moves the window instead of clicking. A `Mouse:LeftClick` fires on release, except when the same modifiers also have a double-click binding and the click's command is not checkable: then the player waits the system's double-click interval to tell a click from a double click. (A checkable command such as play/pause runs at once; a double click runs it twice, which restores its state, and the double-click binding still fires.)
+
+##### The user's bindings
+
+The user can rebind any command, the player's own included. Those **overrides** win over every default binding, are kept across launches, and are stored by plugin id and command id, never by menu path. A plugin with the capability `bindings.manage` (a key-binding settings page) reads and changes them with plugin.bindings:
+
+- `list()` returns every declared command with its default and current inputs, which of them another command shadows, and the overrides whose command does not exist right now (its plugin is stopped); those are kept and apply again when it returns.
+- To find a command by its place in the menu, compare BindingInfo.key (the English menu keys, the same in every language), not `path`, which is the translated text.
+
+#### The player's own commands
+
+The player registers some commands itself, with the owner `host`: **Toggle Fullscreen**, **Leave Fullscreen**, **Quit** and the core playback actions (play/pause, stop, previous/next, frame step, relative seek, speed, volume, mute). They exist whether or not any plugin runs, and the user rebinds them like any other command.
+
+A plugin button that does what a core action does should run that action with plugin.host.run (capability `commands`): it applies the same checks and shows the same on-screen text as the menu item and the key, so a bottom bar's play button and the Space key behave identically. The action ids, their menu places and default keys are in [Reference: commands; what they do to playback is in Playback.
+
+## Concept: Playback state, controls and sources
+
+The player plays one source at a time, and many parties change it: the user, the player's own keys and every plugin. This page explains how a plugin sees that shared state, why its controls are conditional on what it saw, where sources come from (files and URLs, resolvers, streams a plugin generates), and how next/previous and the core actions fit in.
+
+The members are on Player; this page explains how they work together.
+
+#### The playback state
+
+plugin.player.state is a PlayerState: an immutable snapshot of the current source.
+
+```text
+           open()                     media ready               played to the end
+ empty ───────────▶ loading ─────────────────────▶ ready ─────────────────────▶ ended
+   ▲                  │                              │  ▲                          │
+   │                  └── load failed ──▶ error      │  └──── restart() ───────────┘
+   └──────────── close() / F4 ───────────────────────┘
+ every open (even of the same file) starts a new sourceId
+```
+
+- **`sourceId` identifies a source.** It changes every time something is opened, even the same file again, so comparing `sourceId`s tells you whether "the thing playing" is still the one you saw.
+- **`can` says what the source allows**: pause, seek, rate, restart, close, snapshot, next, previous. A live stream cannot seek; a generated stream cannot seek, change speed or restart. Bind your controls' enabled state to it instead of guessing from `kind` or the file type.
+- **`kind` is `"media"` or `"stream"`**, a source the player decodes or one a plugin generates. Tell them apart by `kind`, never by parsing `source`.
+
+Reading it needs `playback.read`; following it needs `events` too:
+
+- The SDK reads the state once before `activate` and, with `events`, keeps `player.state` current and calls onChange listeners after every change. The state **never goes backwards**: a late event that is older than what the plugin already has is dropped.
+- Without `events`, `player.state` stays as it was first read until you call refresh().
+- Some facts are read on demand instead of pushed, because they are large or rarely needed: chapters(), stats() (codecs, frame counts, decoder, bitrates), audioDevices().
+  - In `stats()`, the frame counts come from two places. `framesShown` and `framesDropped` are the video renderer's (mpv's) counts. `presentedFps` is what the player window really showed: new frames per second over the last second. When it stays well below `video.fps` while playing, frames are lost after rendering (the window cannot keep up, or the display refreshes slower). `video.decoding` says whether the video is decoded in `"hardware"` (the method in `video.hwdec`) or `"software"`.
+
+Because the state is a snapshot, a plugin can keep one and use it later as the condition for a control.
+
+#### Conditional controls
+
+**A control acts on the state the plugin saw.** `setPaused`, `seek`, `setRate`, `restart`, `close` and `media.capture` are conditional on the current `player.state` by default. If, after that state, the user or another plugin changed the source (opened something else, paused, jumped to another position), the call fails with `code: "stale"` and **does nothing**.
+
+```text
+plugin sees state #7 (movie.mp4 at 0:42)
+user opens trailer.mp4  ─▶ state #8
+plugin: seek(42)        ─▶ rejected with "stale"; the trailer is not touched
+```
+
+Without this rule, a "jump to bookmark" that arrives a moment late would seek a different video, and two plugins reacting to the same event would undo each other. With it, a late control is refused instead of applied to the wrong thing.
+
+- The SDK refreshes `player.state` after each of its own operations, so a plugin's consecutive controls do not make each other stale.
+- player.open is **unconditional** by default: an open the user asked for should replace whatever plays.
+- To bind a control to an earlier state, keep that state and pass it as `ifCurrent` (Conditional):
+
+  ```ts nocheck
+  // advance to the next item only if nobody changed the source after it ended
+  media.onEnd((ended) => plugin.player.open(next, { ifCurrent: ended }));
+
+  // capture the source the user saw before confirming, not whatever plays now
+  const seen = plugin.player.state;
+  const answer = await plugin.dialogs.confirm({ message: "Capture this frame?", confirm: "Capture" });
+  if (answer.confirmed) await plugin.media.capture({ ifCurrent: seen });
+  ```
+
+- isCurrent(state) answers the same question without acting, for example to warn in a form that the source changed meanwhile.
+- `stale` is not an error to report loudly. It means the user did something else; usually the right reaction is to do nothing.
 
-| SDK package | Plugin `apiVersion` | Notes                                                                                                                                                                                                                                       |
-| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `1.x`       | `vestra/1`          | Minor releases only add backwards-compatible API; patch releases fix documentation and bugs.                                                                                                                                                |
-| `1.1`       | `vestra/1`          | The additions need player 0.2.0: set `"minPlayerVersion": "0.2.0"` when you use them.                                                                                                                                                       |
-| `1.3`       | `vestra/1`          | Menu ids (`@video`), `Theme.danger` and removing a video chain with `[]` need player 0.3.0: set `"minPlayerVersion": "0.3.0"` when you use them.                                                                                            |
-| `1.4`       | `vestra/1`          | One exception to "only add": `ThemeId` lost the second palette and is `"vestra"` only. A plugin that compared with or set the removed id fails to type check; the player treats that id as `vestra`, so already built plugins keep running. |
-| `1.5`       | `vestra/1`          | The light palette `vestra-light` and `@vestra/icons.slint` need player 0.4.0: set `"minPlayerVersion": "0.4.0"` when you use them.                                                                                                          |
+Two controls follow other rules because they are about the device or a gesture, not the source:
 
-A breaking change to the plugin API gets a new `apiVersion` and a new major version of this package. The `@vestra-player/sdk/runtime` entry is for the player only and is not covered by semver.
+- setOutput (volume and mute) is last-write-wins and resolves `false` when a newer value replaced it.
+- scrub() starts a drag gesture on a seek bar: each seek in the gesture is conditional on the previous one, only the newest target is kept, and any outside change ends the gesture. Use it for a slider instead of calling `seek` on every move.
+
+#### Sources
+
+##### Files and URLs
+
+player.open(source) opens a path or URL (capability `playback.control`) and returns a Media handle for what this plugin opened. The promise resolves when the player accepted the open, not when it plays; media.ready() waits for playback to start and rejects with `failed` (it did not load), `replaced` (something else was opened first) or `ended`. onEnd reports each natural end.
+
+A `Media` is not closed when its scope is disposed or the plugin stops: the user is watching it. media.close() closes it only if it is still the current source.
+
+Every way of opening goes through `player.open`: the open dialog, a drop on the video area, a playlist, another plugin. That is what lets resolvers work for all of them.
+
+##### Resolvers
+
+A **resolver** (plugin.resolvers, capability `source.resolve`) lets a plugin take over opening some sources:
+
+- A **web resolver** (`schemes` and exact `hosts`) turns a page URL into stream URLs the player can play (a video site's page into its media URLs, with headers).
+- A **file resolver** (`extensions`, player 0.4.1) takes over local files by extension and returns a stream the plugin generates (an emulator for `.nes` files). It also needs `producer.av`.
+
+```text
+player.open("https://video.example/watch?v=1")     from anyone: user, playlist, plugin
+   │  a resolver registered for https + video.example?
+   ├── no ──▶ the player opens the URL itself
+   ▼ yes
+resolver.resolve(url, signal)   in the resolver plugin's process
+   │  returns stream URLs (web) or a generated stream (file)
+   ▼
+the player opens the result under the original open:
+same ifCurrent condition, same Media, same ready() for the caller
+```
+
+- **One owner per target.** One scheme and host, or one extension, has one resolver. A second plugin's registration fails with `conflict` but does not fail its activation; the player's built-in plugins register first.
+- **The opener does not know.** The plugin that called `open` needs only `playback.control`; it gets its `Media`, `ready()` and errors as for any other source.
+- **Cancellation is a signal.** The resolver's `signal` aborts when the open is replaced or closed, when it takes longer than 30 seconds, and when the resolver or its plugin goes away; a late answer is discarded.
+- **A failure is the open's failure.** When `resolve` throws, the source goes to `phase: "error"` with the error's message as `state.error`; throw `plugin.i18n.error(…)` for a message in the user's language.
+- resolvers.fileTypes lists every extension some plugin resolves, so a playlist or file filter can accept those files too.
+
+##### Generated streams
+
+player.openStream (capability `producer.av`) makes a source whose picture and sound the plugin generates: a signal generator, an emulator, a synthesizer. A file resolver returns the same kind of stream. The SDK calls the plugin's `frame()` on the audio clock (never concurrently, not while paused) and handles buffering, start-up and pausing; frames reach the player over a local connection the SDK sets up.
+
+- `state.kind` is `"stream"`. It cannot seek, change speed or restart, and it **bypasses the filters**: the player does not decode it, so filter chains report `unsupported` while it plays (Video and audio processing).
+- Frame sizes and sample values have limits; a frame that breaks them ends the stream with `invalid` (Reference: limits).
+- Stream.onStop reports only stops from outside (another source, the user closing it, a failure), not the plugin's own `stop()`.
+
+#### Next and previous
+
+The player's **Previous** and **Next** (menu, keys, the bottom bar) are not tied to a playlist. One plugin at a time can **provide the sequence** with provideSequence, giving `next()`, `previous()` and two flags, `canNext` and `canPrevious`, which are bindings re-evaluated in every update pass.
+
+- Every plugin sees the flags as `player.state.can.next` and `can.previous`, and player.next() asks the provider to move; the provider's `next` runs in its own scope.
+- A second provider fails with `conflict` and does not fail activation; it is tried again when its flags change, so it takes over once the first provider goes away.
+- Without a provider, or with the flag false, `next()` fails with `unavailable` and the menu items are disabled.
+
+#### Core actions
+
+Play/pause, stop, previous/next, frame steps, relative seeks, speed, volume and mute are **core actions**: commands the player registers itself, so they work with no plugin running. plugin.host.run(action) runs one exactly as its menu item or key would, with the same checks and the same on-screen text. A plugin's play button should call `host.run("play-pause")` rather than `setPaused`, so that it behaves like the Space key in every case (restart after the end, the "Paused" message, disabled without a source).
+
+The difference from the `Player` methods: a `Player` control is a precise operation the plugin is responsible for (conditional, silent, its own error handling); a core action is the user's action, performed on the plugin's behalf. The action ids, menu places and default keys are in Reference: commands; how keys reach them is in Commands, menus and key bindings.
+
+## Concept: Video and audio processing
+
+A plugin can change what the user sees and hears in three different places. They look alike in the API (each is a handle with `set`, a `status` and `onStatus`), but they act at different stages and have different owners, so choosing the right one matters:
+
+| | Changes | Owner | In snapshots and exports | API |
+| --- | --- | --- | --- | --- |
+| **Filter chain** | The decoded frames and samples: colour, blur, denoise, rotation, crop, volume, equalizer, delay… | Every plugin has its own chains; all are joined | Yes | VideoFilter, AudioFilter |
+| **Display layer** | Where the video sits in the video area: aspect, fit, zoom, pan | One plugin at a time | No | VideoView |
+| **Render options** | How the GPU renderer draws: HDR tone mapping, user shaders, motion interpolation | One plugin at a time | No | RenderOptions |
+
+```text
+ decoder ─▶ plugin A's chain ─▶ plugin B's chain ─▶ … ─▶ (frameBlend) ─▶ renderer ─▶ video area
+            └──────────── filter chains: part of the picture ──────────┘    │          │
+                         snapshots and exports use the same chain      render options  display layer
+                                                                       (display only)  (display only)
+```
+
+All three need `processing.video` (or `processing.audio`) and `playback.read`; filter chains also need `events`, because the SDK must see each new source to apply the chain again.
+
+#### Filter chains
+
+plugin.video.filter(id) and `plugin.audio.filter(id)` give the plugin a chain of its own: a list of nodes (VideoNode, AudioNode) that the player turns into FFmpeg filters.
+
+```ts
+const picture = plugin.video.filter("picture");
+picture.set([{ kind: "eq", brightness: 0.1, contrast: 1.1, saturation: 1, gamma: 1 }]);
+```
+
+- **A chain is a desired state.** `set(nodes)` says what the chain should be from now on; the last write wins. The SDK applies it to the current media, and **applies it again to every new source**, so the plugin does not react to file changes itself.
+- **Each plugin owns its own chains.** The player joins the chains of all plugins in a stable order. Setting or disposing a chain changes only that plugin's contribution; an empty chain (`[]`, or for audio no nodes and no delay) withdraws it and leaves the others alone.
+- **Nothing is sent until the first `set()`**, and disposing a chain that was applied withdraws it.
+- **Limits are shared.** All plugins together have at most 64 nodes, one `frameBlend` and a bounded audio delay (Reference: limits); a value out of a node's range fails with `invalid`.
+- **The same chain is the picture.** A processed snapshot or an export (plugin.media) goes through the same chains, so it matches what plays.
+
+##### Status
+
+A chain reports where it stands in FilterStatus:
+
+```text
+ set(nodes)
+   │ no ready media ──▶ waiting ── media ready ──┐
+   ▼                                             ▼
+ applying ──────────────────────────────────▶ applied
+   │
+   └──▶ failed (error.code) ── retry() / next set() / new source ──▶ applying
+```
+
+- `waiting` keeps the value until there is media to apply it to; without `events` the SDK never sees the media become ready, so the chain stays there.
+- `applied` means the player accepted the chain, not that the next frame already shows it.
+- `failed` is not retried by itself. Its `error.code` says why: `invalid` (a value out of range), `unsupported` (the source is a generated stream, which the player does not decode; the chain is applied again once a decoded source plays), `backend-uncertain` (the player's backend blocked that stage; call `retry()`).
+
+##### Live parameters
+
+A slider that drives a filter calls `set` on every move. That is fine: one request is in flight at a time and only the newest value is sent (Keep a slider responsive while dragging).
+
+How smoothly the change shows depends on the field. Some fields, marked **live** on VideoNode and AudioNode (brightness and contrast, blur strength, hue, volume, equalizer gain…), change in place while playing. Changing any other field rebuilds that stage of the chain: the picture may stall for a frame and an audio filter's internal state starts over. Put the live fields on the controls users drag, and the others on switches and lists.
+
+##### Ordering and side effects
+
+- Video nodes act on the picture after the player has applied the container's rotation, so a portrait video is upright before a plugin's `transform` rotates it.
+- `frameBlend` (frame-rate conversion by blending) always runs **last**, after every plugin's chain, wherever it is written, so temporal filters such as denoise and deinterlace still see the original frames. It changes the frame rate of exports too, and costs a lot of CPU: decide from `stats()` whether to offer it.
+- Filters need frames in memory. While any plugin has a video chain, the player decodes in hardware with a copy back to memory instead of zero-copy decoding; when the last chain is removed it switches back. The decoder restarts at each switch, so the picture may pause briefly. stats().video.hwdec shows the decoder in use.
+
+#### The display layer
+
+plugin.video.view() returns the VideoView: aspect override, fit (keep with bars, stretch, fill and crop), zoom and pan. It changes only how the frames are placed in the video area. Snapshots, exports and filters do not see it.
+
+- **One owner.** The first plugin to call `view()` owns the display layer. Another plugin's handle reports `failed` with `conflict` and tries again on each `set`, so it takes over once the owner disposes its view or stops. When the owner lets go, the player restores the defaults.
+- **Writes merge.** `set({ zoom: 1.5 })` changes only the zoom; the other fields keep their values.
+- **Values stay across sources**, as in mpv. A plugin that wants "reset zoom for every new file" does that itself when `player.state.sourceId` changes.
+
+#### Render options
+
+plugin.video.render() returns the RenderOptions of the GPU renderer: HDR to SDR tone mapping and the display's brightness, user shaders (`.glsl` files) and motion interpolation. Like the display layer they act at display time only, have one owner (independent of the display layer's owner) and merge writes.
+
+- **Only the GPU renderer has them.** Under software rendering every `set` fails with `unsupported`; see Reference: platforms for where the player renders on the GPU. Treat `unsupported` as "hide these settings", not as an error.
+- A shader that does not compile is reported later: the status first becomes `applied`, then `failed` with code `failed` and the compiler's first error line once mpv first uses the shader.
 
 ## Concept: Windows, panels, settings pages, dialogs and the OSD
 
@@ -284,7 +667,7 @@ A plugin can show its own user interface in five places. Three of them are drawn
 
 It assumes you have written a first plugin (Getting started). For every method's parameters and errors, follow the links into the API reference.
 
-### The five surfaces
+#### The five surfaces
 
 ```text
 ┌─ main window ─────────────────────────────────────────┬─────────────┐
@@ -312,7 +695,7 @@ It assumes you have written a first plugin (Getting started). For every method's
 
 **⑤ Dialogs** (plugin.dialogs, `ui.dialog`). The system's own dialogs: a confirmation alert (confirm) and the open-file, open-folder and save-file dialogs. The plugin passes text and gets an answer back; it does not draw anything. Only one dialog is open at a time, player-wide.
 
-### Choosing a surface
+#### Choosing a surface
 
 | You want to…                                                                                  | Use                                                                        | Why not the others                                                                       |
 | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
@@ -322,19 +705,19 @@ It assumes you have written a first plugin (Getting started). For every method's
 | Cover art or an idle screen while nothing is playing                                          | Panel in the `backdrop` slot                                               | It replaces the black video area; one plugin at a time.                                  |
 | A tool the user opens, uses and closes: picture adjustments, an inspector, an editor          | Tool window                                                                | It has its own title bar and size and does not take space from the video.                |
 | Preferences that rarely change                                                                | Settings page                                                              | Users look for preferences in Options; the player keeps the window and its navigation.   |
-| A yes/no question before something destructive                                                | Dialogs.confirm dialogs.confirm               | Native look and keyboard handling (Enter, Escape); no Slint file.                        |
-| A file or folder from the user                                                                | Dialogs.openFile dialogs.openFile and friends | The system dialog is the only one users trust with paths.                                |
+| A yes/no question before something destructive                                                | dialogs.confirm               | Native look and keyboard handling (Enter, Escape); no Slint file.                        |
+| A file or folder from the user                                                                | dialogs.openFile and friends | The system dialog is the only one users trust with paths.                                |
 
 Two rules of thumb:
 
 - **Prefer the smallest surface that works.** An OSD message before a dialog, a settings page before a tool window. Every window the user has to close is a cost.
 - **Panels are shared space.** There is one sidebar, one bottom bar and one backdrop for all plugins. The sidebar holds several panels as tabs (the player draws the tab strip while there are two or more; showing, hiding and detaching apply to all of them). The bottom bar and the backdrop hold one: while one plugin's panel is there, another plugin's mount rejects with `conflict`, which does not fail its activation. Mount a panel only when the plugin's main purpose is to live there.
 
-### Life cycles
+#### Life cycles
 
 Every surface is a **handle** owned by the Scope that created it. Disposing the scope (or the plugin stopping) releases it: windows close, panels are unmounted, settings pages leave the Options window, the info block disappears. A plugin never has to clean up its interface by hand.
 
-#### Tool window
+##### Tool window
 
 ```text
  windows.create(file)       nothing on screen yet; bind callbacks and properties now
@@ -346,7 +729,7 @@ Every surface is a **handle** owned by the Scope that created it. Disposing the
  └──────────────┘           └──────────────┘   show()   └──────────────┘
         ▲                       │       │
         │  close()              │       │  the user: title-bar close button,
-        │  (no onClose)         │       │  ⌘W (macOS), Ctrl+W or Ctrl+F4 (Windows)
+        │  (no onClose)         │       │  the standard close keys
         └───────────────────────┘       │  → onClose listeners run
         ▲                               │
         └───────────────────────────────┘
@@ -358,7 +741,7 @@ Every surface is a **handle** owned by the Scope that created it. Disposing the
 - `close()` and a user close both destroy the window instance. The handle stays usable: the next `show()` opens a **fresh** instance with the current properties (whatever the user typed into fields that the plugin did not record is gone).
 - Only a user close calls onClose. Stop timers and polling there.
 
-#### Panel
+##### Panel
 
 ```text
  panels.mount(slot, file)
@@ -380,7 +763,7 @@ Every surface is a **handle** owned by the Scope that created it. Disposing the
 - The position (`plugin.panels.bottom`, `.sidebar`) is separate from the panel: it has the user's preference (`preferred`), whether it is on screen now (`effective`) and why not (`reason`), and its tabs (`panels`). Any plugin with `ui.mount` can read and toggle it, so a "Show playlist" command can live in a different plugin than the playlist. The panel's own state (Panel.state) adds whether its tab is the current one (`reason: "otherTab"` when not); Panel.toggle brings a background tab forward instead of closing the sidebar.
 - The player remembers the sidebar's visibility, width, detached state and floating window position across launches.
 
-#### Settings page
+##### Settings page
 
 ```text
  settings.page(file, { id, category, title })
@@ -398,23 +781,23 @@ Every surface is a **handle** owned by the Scope that created it. Disposing the
 - The Options window belongs to the player. The page exists from `ready` on, whether or not the window is open; property writes while it is closed are kept and applied when it opens.
 - The page is compiled alone at registration, so a broken page fails its own `ready` and not the whole window.
 
-#### Dialogs and the OSD
+##### Dialogs and the OSD
 
 - Dialogs are one call each: the promise resolves when the user answers. There is no time limit and no way to close a dialog from code. Playback continues while it is open; command key bindings pause.
 - The OSD message is fire-and-forget; a newer message (from any plugin) replaces the current one. The info block is a handle: `set(text)` shows or changes it, `set(null)` hides it, disposing removes it.
 
-### How Slint and TypeScript talk
+#### How Slint and TypeScript talk
 
 The plugin process and the user interface run in different processes: your TypeScript runs in the plugin's Node.js process, the Slint files run inside the player. They exchange exactly two kinds of messages:
 
 | Direction   | Slint side                               | TypeScript side                                                                              |
 | ----------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
-| plugin → UI | `in property` or `in-out property`       | View.set set() or View.bind bind() |
-| UI → plugin | `callback name(args);` returning nothing | View.on on("name", handler)                                     |
+| plugin → UI | `in property` or `in-out property`       | set() or bind() |
+| UI → plugin | `callback name(args);` returning nothing | on("name", handler)                                     |
 
 A tool window (Window), a panel (Panel) and a settings page (SettingsPage) all share this View surface. Nothing else crosses: the plugin cannot call Slint functions or read a property back; a value the user changes reaches the plugin only through a callback.
 
-#### Where the properties live: component or global
+##### Where the properties live: component or global
 
 - **A tool window file exports exactly one component**, usually `export component X inherits Window`. Its properties and callbacks are declared on that component. The window is yours, so the component is the window.
 - **A panel or settings page file exports one component and one global.** The player composes your component into a window it owns (the main window, the floating sidebar window, the Options window), so the component instance is not a stable address: a new instance is made whenever the main window is rebuilt or the sidebar moves to or from its floating window. The **global** is the bridge: properties and callbacks are declared on it, the component reads and calls them (`ListBridge.rows`, `ListBridge.select(index)`), and the plugin talks to the global. The SDK finds the two names from the file's `export component` and `export global` lines.
@@ -462,15 +845,21 @@ export component ListPanel inherits Rectangle {
 }
 ```
 
-Helper components without `export` are allowed in every file. The player appends a line that exports its palette to every plugin file, so do not declare anything named `VestraPalette`.
+##### Rules for plugin Slint files
+
+- **Exactly one exported component** per file (plus the one bridge global in a panel or settings page file). Helper components without `export` are allowed. The player appends a line that exports its palette to every plugin file, so do not declare anything named `VestraPalette`.
+- **The `fluent-dark` style.** Every plugin file is compiled with Slint's `fluent-dark` style, so `std-widgets.slint` controls (`CheckBox`, `ComboBox`, `Switch`, `LineEdit`…) are dark; in the light palette the player switches them to their light colours (`Palette.color-scheme`) at run time. Do not set `Palette.color-scheme` yourself.
+- **No fonts of your own.** Every window uses the system's interface font, and a character it lacks (CJK text in a Latin font, for example) falls back per character to a font for its script; on Windows the player sets that chain itself and ends it with a bundled CJK font. A plugin does not need to set a font; a `default-font-family` or `font-family` you set still applies, with the same fallback. The fonts per system are in Reference: theme.
+- **Editor support through `libraryPaths`.** The `@vestra/…` imports resolve inside the player. For the Slint language server, point `libraryPaths` at the read-only copy in the SDK package: `{ "vestra": "node_modules/@vestra-player/sdk/slint/vestra" }`.
+- **Text the user sees is `@tr("English")`**, translated when the player loads the file (Translate a plugin).
 
-#### Names and values
+##### Names and values
 
 - Write names in camelCase or kebab-case in TypeScript: the SDK turns every capital letter into `-` plus the lower-case letter (`canMark` → `can-mark`, `strengthChanged` → `strength-changed`). Fields inside struct values are **not** converted, so spell struct fields exactly as the Slint struct does (and without `_`, which Slint treats as `-`).
 - Values must be JSON: booleans, numbers, strings, arrays (Slint models) and objects (Slint structs). Two exceptions: an image from ui.image, only as the **whole** value of an `image` property (nested in an array or object it is `invalid`), and a document from ui.markdown wherever the Slint type is `[MarkdownBlock]`: the whole value, or (SDK 1.5.4, the player after 0.4.0) a field at any depth, such as the `body` of each message in a chat list.
 - Every name must exist in the Slint file. Writing a property the file does not declare makes a tool window's `show()` or a panel's `ready` fail, and in a settings page it keeps the Options window from opening; for a tool window, so does a callback bound with `on()` that the file does not declare. Once the view is open, such writes are reported to onError.
 
-#### set, bind and the update pass
+##### set, bind and the update pass
 
 `set(props)` writes now. `bind(() => props)` declares that properties should _always_ equal a function of your state; the SDK re-evaluates every bound function in an **update pass** and sends only the values that changed.
 
@@ -481,17 +870,11 @@ Helper components without `export` are allowed in every file. The player appends
 | Write fails      | Retried with back-off (0.25 s doubling up to 30 s).                                     | Not repeated until the value changes.                                                 |
 | Typical use      | One-off values: a document, a reset.                                                    | Everything derived from plugin state: labels, enabled flags, lists, status lines.     |
 
-Update passes run:
-
-- after every handler the SDK calls (a command's `run`, a view callback, an `onChange` listener) returns, and again when its promise settles;
-- after player, subtitle, panel position, filter and export state changes;
-- when you call plugin.update().
-
-Several requests in the same microtask are merged into one pass, and each view has at most one write in flight: values that change meanwhile are merged into the next write. So binding a value that changes 60 times a second costs at most one write per round trip, never a queue.
+Update passes run after every handler the SDK calls, after player and other state changes, and when you call plugin.update(); several requests are merged into one pass, and each view has at most one write in flight (The update pass has the details).
 
 The rule to remember: **state you change after an `await` inside a handler appears only when the handler finishes**, unless something else triggers a pass. Call `plugin.update()` right after changing it (see Keep a slider responsive while dragging).
 
-#### Two-way controls
+##### Two-way controls
 
 A control whose value both the user and the plugin change (a slider, a switch, a text field, a combo box) needs a **two-way binding to an `in-out` property**:
 
@@ -506,7 +889,7 @@ Slider {
 
 A one-way binding (`value: root.strength`) is broken by Slint the first time the user moves the control; after that the plugin's writes no longer move it. In a panel or settings page the same applies to the global: `checked <=> MyBridge.enabled`.
 
-### Theme and widgets
+#### Theme and widgets
 
 Plugin Slint files import the player's design tokens and widgets:
 
@@ -517,39 +900,12 @@ import { Button, Slider, ToolTipArea, UrlInputRow } from "@vestra/widgets.slint"
 import { MarkdownView, MarkdownBlocks, MarkdownBlock } from "@vestra/markdown.slint";
 ```
 
-- **Colours follow the player's palette.** The player has two palettes, `vestra` (dark, the default) and `vestra-light` (player 0.4.0, SDK 1.5), both drawn from the logo's colours: a magenta accent, cyan for what is playing, an amber → magenta → violet → cyan gradient for fills (see plugin.appearance). It sets the palette on every view before it appears and again when the user switches, so `Theme` colours change with it. Colours you hard-code do not. `Theme` properties are read-only.
+- **Colours follow the player's palette.** The player has two palettes, `vestra` (dark, the default) and `vestra-light` (player 0.4.0, SDK 1.5), both drawn from the logo's colours (see plugin.appearance). It sets the palette on every view before it appears and again when the user switches, so `Theme` colours change with it. Colours you hard-code do not. `Theme` properties are read-only.
 - **The video area is dark in every palette** (`Theme.bg-video`). Text or icons you draw over the video (a backdrop, an overlay) use light colours, not `Theme.text`, which is dark in `vestra-light`.
-- Colour tokens: `bg-bar`, `bg-video`, `bg-list`, `bg-panel`, `line`, `hover-bg`, `press-bg`, `selected-bg`, `text`, `text-dim`, `text-list`, `text-played`, `accent`, `accent-press`, `accent-disabled`, `icon-disabled`, `playing`, `button-bg`, `button-hover`, `button-press`, `button-disabled`, `accent-fill` (a gradient brush) and `danger` (errors and destructive actions: a failed status line, a Delete button; player 0.3.0, SDK 1.3).
-- Fonts: every window uses the system UI font (Slint falls back per character for scripts it lacks, CJK included); `Theme.font-mono` is the system's monospace family (Menlo on macOS, Consolas on Windows). Sizes: `font-xs` 9px, `font-body` 11px, `font-tab` 12px, `font-title` 13px.
-- Control sizes and spacing: `button-height` 21px, `input-height` 21px, `form-row-gap` 26px, `dialog-padding` 14px, `radius-control` 4px (controls, rows, hover plates), `radius-panel` 8px (menus, panels) and others; the full list is the SDK's read-only copy in [`slint/vestra/theme.slint`](https://github.com/vestrasys/vestra-player-sdk/blob/main/slint/vestra/theme.slint). Player 0.4.0 rounded the corners (3px and 6px before).
-- **Icons** (player 0.4.0, SDK 1.5): `Icon { name: "play"; color: Theme.text; }` draws one icon of the player's own set: round-capped 1.5px lines (1.25px for small glyphs), never filled, in the icon's own box (its default size; set `width` and `height` to scale). Names: `play`, `pause`, `stop`, `back`, `forward`, `open`, `volume`, `mute`, `playlist`, `detach`, `attach`, `close`, `failed`, `move-top`, `move-up`, `move-down`, `move-bottom`, `search`, `chapter`, `bookmark`, `check-task`, `check-box`, `menu-check`, `submenu`, `scroll-up`, `scroll-down`, `caret-down`, `sort-asc`, `sort-desc`, `tag-remove`, `preview-play`, `add`, `remove`, `sort`; `Icons.commands(name)`, `Icons.box-width(name)`, `Icons.box-height(name)` and `Icons.line(name)` give the path data for your own `Path`. Plugins that use it set `"minPlayerVersion": "0.4.0"`.
-- Every plugin file is compiled with Slint's `fluent-dark` style, so `std-widgets.slint` controls (`CheckBox`, `ComboBox`, `Switch`, `LineEdit`…) are dark too; in `vestra-light` the player switches them to their light colours (`Palette.color-scheme`) at run time. Do not set `Palette.color-scheme` yourself.
-- **Markdown** (`@vestra/markdown.slint`): `MarkdownView` scrolls one document; `MarkdownBlocks` (SDK 1.5.4, the player after 0.4.0) draws one without scrolling, as tall as its content, for your own layout or a `ListView` row. Both take `blocks: [MarkdownBlock]`, report `link-clicked(url)`, and with `code-copy: true` (default `false`) put a 复制 button on code blocks that reports `copy-code(code)`; copy it with plugin.clipboard. A chat window:
-
-  ```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); }
-              }
-          }
-      }
-  }
-  ```
+- **Use tokens, not values.** `Theme` has colour tokens (`text`, `accent`, `danger` for errors and destructive actions…), font sizes, control sizes and spacing; `Icon { name: "play"; color: Theme.text; }` draws an icon of the player's own set (player 0.4.0, SDK 1.5, so set `"minPlayerVersion": "0.4.0"`); `@vestra/widgets.slint` has the compact `Button`, `Slider`, `ToolTipArea` and `UrlInputRow`. Every token with its current values in both palettes, the icon names and the widgets' properties are in Reference: theme. The values may change between player versions; the tokens keep their meaning.
+- **Markdown** (`@vestra/markdown.slint`): `MarkdownView` scrolls one document; `MarkdownBlocks` (SDK 1.5.4, the player after 0.4.0) draws one without scrolling, as tall as its content, for your own layout or a `ListView` row. Both take `blocks: [MarkdownBlock]`, report `link-clicked(url)`, and with `code-copy: true` (default `false`) put a **Copy** button on code blocks (`@tr("Copy")`, which the player translates into the interface language) that reports `copy-code(code)`; copy it with plugin.clipboard. A list of documents (a chat, one message per row) is the example at Ui.markdown; Example: Markdown shows one document in a window.
 
-  Write the list with a document per row (`messages: [{ id, role, body: await plugin.ui.markdown(text) }]`). The player parses only the documents that changed and updates the list in place (rows added or removed at the end, a growing message's changed blocks), so re-sending the whole list on every streamed chunk keeps the scroll position and costs little.
-- For editor support, point the Slint language server's `libraryPaths` at the copy in the SDK package: `{ "vestra": "node_modules/@vestra-player/sdk/slint/vestra" }`.
-
-### Sizes
+#### Sizes
 
 All sizes are logical pixels (Slint's `px`): one logical pixel is two physical pixels on a Retina display or at 200 % scaling.
 
@@ -564,25 +920,18 @@ All sizes are logical pixels (Slint's `px`): one logical pixel is two physical p
 
 The operating system places a tool window when it opens; the player does not remember tool window positions or sizes, and the API cannot read or set them. To keep a tool window's _content_ across runs, see Remember a window's state between runs.
 
-### Focus and keyboard
+#### Focus and keyboard
 
 - **Command key bindings belong to the main window.** A binding from CommandOptions.bindings fires while the main window or the floating sidebar window has focus (and the key was not taken by a focused control, such as Space in a text field). It does **not** fire while a tool window or the Options window has focus. Keys inside your own window are Slint's job: use a `FocusScope` with `key-pressed`, or a button's default action.
 - A binding with `focus: "panel"` fires only while this plugin's panel (docked or floating) has focus, and wins over global bindings there.
-- **Standard close keys are not bindings.** ⌘W on macOS, Ctrl+W and Ctrl+F4 on Windows close a tool window, the floating sidebar or the Options window exactly like the title-bar button (a tool window's `onClose` runs). The player takes these keys before Slint sees them, even when a text field has focus, so neither your Slint handlers nor your bindings receive them. The main window does not react to them, so a `Ctrl+W` binding still fires there.
+- **Standard close keys are not bindings.** They close a tool window, the floating sidebar or the Options window like the title-bar button (`onClose` runs) before your Slint handlers or bindings see them; the keys per system are in Keys the system takes first.
 - While a menu or a system dialog is open, bindings pause.
 
-### Platform differences
-
-|                                                | macOS                                                                                 | Windows                                                                                                                                                                               |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Close a tool window, floating sidebar, Options | ⌘W                                                                                    | Ctrl+W, Ctrl+F4                                                                                                                                                                       |
-| `dialogs.confirm`                              | An `NSAlert` sheet on the active player window (the tool window that asked, usually). | A task dialog owned by the active player window, titled "Vestra Player"; `destructive` shows a warning icon; a `checkbox` is asked as a second yes/no dialog after the user confirms. |
-| `Theme.font-mono`                              | Menlo                                                                                 | Consolas                                                                                                                                                                              |
-| `DropModifiers.cmd`                            | ⌘                                                                                     | Ctrl                                                                                                                                                                                  |
+#### Platform differences
 
-The API is the same on both systems. Other systems answer `dialogs.confirm` with `unsupported`. When the player runs without a user interface (headless, as in some automated setups), opening windows, mounting panels, dialogs, the OSD and `settings.show` fail with `unavailable`.
+The API is the same on macOS and Windows; what differs is the system's own part: the standard close keys, how `dialogs.confirm` looks, the monospace font, the modifier `DropModifiers.cmd` stands for. Reference: platforms lists every difference. When the player runs without a user interface (headless, as in some automated setups), opening windows, mounting panels, dialogs, the OSD and `settings.show` fail with `unavailable`.
 
-### Common pitfalls
+#### Common pitfalls
 
 - **A window callback bound after the first `show()`.** It throws. Bind all callbacks right after `create()`; re-binding a name that already has a handler is fine.
 - **A one-way binding on a control.** `value: root.x` stops following the plugin after the user touches the control. Use `in-out` and `<=>`.
@@ -595,34 +944,9 @@ The API is the same on both systems. Other systems answer `dialogs.confirm` with
 - **Two of a kind.** One panel per plugin, one backdrop per player, one OSD info block per plugin, one open dialog at a time (`busy`).
 - **Slot state without `events`.** PanelSlot.state, appearance.theme and their `onChange` listeners follow other plugins and the user only with the `events` capability.
 
-### Testing
-
-`TestHost` from `@vestra-player/sdk/testing` runs a plugin without the player and records its interface: `host.window(id)` (`props`, `callbacks`, `visible`, `emit(callback, ...args)`, `userClose()`), `host.mounted()` for the panel, `host.settingsPage(id)` and `host.settings`, `host.osd` (messages shown), `host.confirms` and `host.dialogAnswers`. Property names in `props` are the Slint (kebab-case) names. The test host does not compile Slint files; check them by running the plugin in the player.
-
-```ts
-import assert from "node:assert/strict";
-import test from "node:test";
-import type { Plugin } from "@vestra-player/sdk";
-import { startPlugin } from "@vestra-player/sdk/testing";
-
-async function activate(plugin: Plugin) {
-  let count = 0;
-  const window = plugin.windows.create("ui/counter.slint");
-  window.bind(() => ({ label: `Clicked ${count} times` }));
-  window.on("clicked", () => count++);
-  await window.show();
-}
+#### Testing
 
-test("the label counts clicks", async () => {
-  const { host, stop } = await startPlugin(activate, {
-    capabilities: ["ui.window"],
-  });
-  host.window("counter").emit("clicked");
-  await host.settle();
-  assert.equal(host.window("counter").props["label"], "Clicked 1 times");
-  await stop();
-});
-```
+`TestHost` from `@vestra-player/sdk/testing` runs a plugin without the player and records its interface: windows with their properties and callbacks, the mounted panel, settings pages, the OSD and dialogs. It does not compile Slint files; check them by running the plugin in the player. How to write such tests is in Test a plugin.
 
 ## How-to: Keep a slider responsive while dragging
 
@@ -630,7 +954,7 @@ test("the label counts clicks", async () => {
 
 A slider reports every pointer movement, often more than 60 times a second. Each report is a callback in your plugin. The plugin stays responsive if every callback only **records the newest value and hands it to something that keeps only the newest value**. It stutters when every callback starts its own slow request and the requests queue up behind each other.
 
-### The complete example
+#### The complete example
 
 A **Brightness** window with a slider from −1 to 1, a value label and a Reset button. The video follows the slider while it moves; an on-screen message reports the value when the user lets go.
 
@@ -738,196 +1062,1927 @@ export default async function activate(plugin: Plugin) {
 }
 ```
 
-### Why this stays smooth
+#### Why this stays smooth
 
 1. **The callback does not wait.** `brightnessChanged` updates a variable and calls `filter.set()`, which returns at once. The SDK runs the next callback as soon as it arrives.
 2. **The expensive part keeps only the newest value.** `filter.set()` has _latest-value_ semantics: while one request is in flight, newer values replace each other and only the last one is sent. A fast drag costs a request per round trip to the player, not one per pointer move, and the video ends exactly where the slider stopped.
 3. **The slider's value is bound, not set.** `bind` sends `brightness` only when it differs from what was sent last, and the player skips a write that equals what the slider already shows. So the plugin never fights the user's pointer, yet Reset (which changes the model) moves the thumb.
 4. **Work that should happen once happens on release.** The on-screen message (and anything like saving or logging) waits for `brightnessReleased`, which fires once per drag.
 
-The Slint side needs two things: an `in-out` property and a two-way binding (`value <=> root.brightness`). With a one-way binding (`value: root.brightness`) Slint breaks the binding the first time the user drags, and Reset stops moving the thumb.
+The Slint side needs two things: an `in-out` property and a two-way binding (`value <=> root.brightness`). With a one-way binding (`value: root.brightness`) Slint breaks the binding the first time the user drags, and Reset stops moving the thumb.
+
+#### Which calls keep only the newest value
+
+| Latest value wins (safe on every move)                                                                                 | One request per call (do not call on every move)                                                                                                      |
+| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| VideoFilter`.set`, AudioFilter`.set` | player.seek: use player.scrub() and `Scrub.seek` for a seek slider |
+| player.setOutput (volume, mute)                                          | `player.setRate` and other player controls                                                                                                            |
+| `Scrub.seek` (about one seek per display frame)                                                                        | osd.show: show a message on release                                                                             |
+| View properties (`bind`, `set`), OsdPanel.set                                | `JsonStore.save` is debounced (300 ms), so it is fine; anything you write yourself is not                                                             |
+
+#### When the slow part is your own code
+
+If a move triggers your own asynchronous work (rendering a preview with `plugin.tools.run`, a network request), do not `await` it per callback: the SDK starts every callback without waiting for the previous one, so slow runs overlap and can finish out of order, leaving an _older_ result on screen. Give that work latest-value semantics yourself:
+
+```ts
+import type { Plugin } from "@vestra-player/sdk";
+
+/** Run `work` for the newest value only: one run at a time; values that arrive meanwhile replace each other. */
+export function latest<T>(work: (value: T) => Promise<void>) {
+  let running = false;
+  let next: { value: T } | undefined;
+  return async (value: T) => {
+    next = { value };
+    if (running) return; // the running loop picks it up
+    running = true;
+    try {
+      while (next) {
+        const current = next.value;
+        next = undefined;
+        await work(current);
+      }
+    } finally {
+      running = false;
+    }
+  };
+}
+
+declare function renderPreview(strength: number): Promise<string>; // your own slow work
+
+export default async function activate(plugin: Plugin) {
+  let preview = "";
+  const window = plugin.windows.create("ui/preview.slint");
+  window.bind(() => ({ preview }));
+  const refresh = latest(async (strength: number) => {
+    preview = await renderPreview(strength);
+    plugin.update(); // changed after an await: send it now
+  });
+  window.on("strengthChanged", (strength: number) => refresh(strength));
+}
+```
+
+`plugin.update()` matters here. The SDK re-evaluates bound properties after a callback returns and again when its promise settles; a value you change **after an `await`** inside a longer task is otherwise shown only when that task ends. Call `plugin.update()` whenever such a task has something new to show.
+
+## How-to: Remember a window's state between runs
+
+**Goal:** a tool window comes back the way the user left it: its controls hold the last values, and if it was open when the player quit, it opens again at the next start.
+
+A tool window keeps nothing by itself: closing it destroys the window instance, and the plugin process ends with the player. Keep the state in your plugin, store it with plugin.storage.json, show it with `bind`, and reopen the window during activation.
+
+#### The complete example
+
+The **Brightness** window from Keep a slider responsive while dragging, now remembering the brightness and whether the window was open. The manifest is the same as there, without `ui.osd`:
+
+```json
+{
+  "id": "examples.brightness",
+  "version": "1.0.0",
+  "apiVersion": "vestra/1",
+  "entry": "main.ts",
+  "minPlayerVersion": "0.3.0",
+  "capabilities": [
+    "commands",
+    "ui.window",
+    "processing.video",
+    "playback.read",
+    "events"
+  ]
+}
+```
+
+`ui/brightness.slint` is unchanged: it declares `in-out property <float> brightness`, `in property <string> label` and the callbacks `brightness-changed(float)`, `brightness-released(float)` and `reset()` (the full file is on the slider page).
+
+`main.ts`:
+
+```ts
+import type { Plugin } from "@vestra-player/sdk";
+
+/** Everything the plugin remembers, in <dataDirectory>/brightness.json. */
+interface Saved {
+  /** −1–1, 0 = unchanged. */
+  brightness: number;
+  /** The window was open when the player quit. */
+  open: boolean;
+}
+
+const DEFAULTS: Saved = { brightness: 0, open: false };
+
+/** A missing, broken or outdated file falls back to DEFAULTS. */
+function isSaved(value: unknown): value is Saved {
+  const v = value as Partial<Saved> | null;
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof v.brightness === "number" &&
+    Math.abs(v.brightness) <= 1 &&
+    typeof v.open === "boolean"
+  );
+}
+
+export default async function activate(plugin: Plugin) {
+  // 1. Load: read once, synchronously; defaults if there is no valid file.
+  const store = plugin.storage.json<Saved>("brightness", {
+    defaults: DEFAULTS,
+    validate: isSaved,
+  });
+  /** Change part of the state; the file is written 300 ms after the last change. */
+  const remember = (patch: Partial<Saved>) =>
+    store.save({ ...store.value, ...patch });
+
+  const filter = plugin.video.filter("brightness");
+  const apply = () =>
+    filter.set([
+      {
+        kind: "eq",
+        brightness: store.value.brightness,
+        contrast: 1,
+        saturation: 1,
+        gamma: 1,
+      },
+    ]);
+  apply(); // the effect is back before the window is
+
+  // 2. Show: the window always displays the stored state.
+  const window = plugin.windows.create("ui/brightness.slint");
+  window.bind(() => ({
+    brightness: store.value.brightness,
+    label: store.value.brightness.toFixed(2),
+  }));
+  window.on("brightnessChanged", (value: number) => {
+    remember({ brightness: Math.min(1, Math.max(-1, value)) });
+    apply();
+  });
+  window.on("reset", () => {
+    remember({ brightness: 0 });
+    apply();
+  });
+
+  // 3. Track whether it is open: only the user closing it counts as "closed".
+  window.onClose(() => remember({ open: false }));
+  const open = async () => {
+    await window.show();
+    remember({ open: true });
+  };
+  plugin.commands.add({
+    id: "brightness",
+    path: ["@video", "Brightness…"],
+    run: open,
+  });
+
+  // 4. Restore: reopen it if it was open when the player quit.
+  if (store.value.open) await open().catch(() => remember({ open: false }));
+}
+```
+
+#### How it works
+
+- **Load once, at activation.** `storage.json` reads `<dataDirectory>/brightness.json` synchronously when it is created. A file that cannot be parsed or fails `validate` is renamed to `brightness.json.bad-<timestamp>` and `defaults` is used, so a damaged or older file never breaks the plugin. Always pass a `validate` function: the file is outside your control.
+- **Bind the stored value, not a copy.** `window.bind` reads `store.value` in every update pass, so whatever changes the state (a callback, Reset, a command) updates the window, and a window opened later starts with the current values.
+- **Save on every change; the store debounces.** `save()` replaces `store.value` at once and writes the file 300 ms after the last call (a temporary file, then a rename). Dragging the slider writes the file once, after the drag. When the plugin stops (the player quits, the user disables the plugin), the store is flushed, so the last value is not lost.
+- **"Open" means "the user did not close it".** `onClose` runs only when the user closes the window (the title-bar button or the standard close keys). When the player quits, the plugin stops and its windows close _without_ `onClose`, so `open` stays `true` and the window comes back next time. That is the behaviour users expect from an application's tool windows.
+- **Restore after binding.** The window is created and bound before `open()` runs, so it opens with the stored values and without flashing defaults. If it cannot open (for example in a player without a user interface), the plugin forgets that it was open instead of failing activation.
+
+#### What you cannot restore
+
+- **Position and size.** The operating system places a tool window when it opens. The player does not remember tool window frames, and the API has no way to read or set them; the window's size comes from its Slint file (`width`, `preferred-width` and so on).
+- **State that only Slint knows.** Text in a field, a scroll position or a selected tab survives only if a callback reports it to the plugin and the plugin stores it and writes it back as a property, as `brightness` does here.
+
+#### Variations
+
+- **Several windows from one file** (one per document, created with `windows.create(file, { id })`): store an object keyed by the window id and restore each one.
+- **Preferences rather than state:** a choice such as "reopen my windows at startup" belongs on a settings page (plugin.settings.page) that reads and writes the same store (the `SettingsPage` reference has an example).
+- **Large or binary data:** write your own files in plugin.dataDirectory (to a temporary name, then rename) and keep only small settings in `storage.json`.
+
+## How-to: Translate a plugin
+
+Vestra Player (0.4.3 or later) shows its interface in one of seven languages. The user picks one in **Settings ▸ Language** (or follows the system); the choice takes effect at the next start, and the language stays the same for the whole run. A plugin joins in by shipping one gettext file per language. It writes **no translation code**: the player translates.
+
+The Counter example is a complete translated plugin. Moving an existing plugin over is in Migrate a plugin to English source text.
+
+#### The rule: English source text in three places
+
+Every text a user can see is written in English, in one of three places, and the player looks it up in the plugin's catalog for the interface language. Untranslated text shows in English.
+
+1. **Declarations.** What the plugin declares, the player shows translated:
+
+   ```ts nocheck
+   plugin.commands.add({
+     id: "counter",
+     path: ["Tools", "Counter…"], // English: menus merge by these words
+     run: () => window.show(),
+   });
+   ```
+
+   Command titles and paths, settings page titles (`settings.page`), panel and tab titles (`panels.mount`), command `reason`s, and the manifest's `name`, `punchline`, `description` and `tags`. Menus of different plugins merge by the English words, so plugins that share a submenu must write it the same way; the player's own menus are `Open`, `Playback`, `Subtitles`, `Video`, `Audio`, `Screen`, `Settings` (or `@video` and the other ids) and show in the player's words.
+
+2. **Slint.** A window's texts belong in its `.slint` file, wrapped in `@tr`:
+
+   ```slint
+   title: @tr("Counter");
+   Text { text: @tr("{n} click" | "{n} clicks" % root.count); }
+   Button { text: @tr("Add {}", root.step); }
+   ```
+
+   TypeScript passes data (`count`, `step`), never finished sentences. `@tr` takes `{}`, `{0}`, `{1}` arguments and a plural form (`"one" | "other" % n`, where `{n}` is the number). The player has two plural forms: one for `n == 1`, the other for every other number. A context (`@tr("Menu" => "Open")`) tells two meanings of one English word apart.
+
+3. **Sentences the plugin hands the player**: `osd.show`, `OsdPanel.set` and `dialogs.confirm` take a template and its arguments:
+
+   ```ts nocheck
+   await plugin.osd.show("Speed {}×", [rate]);
+   await plugin.dialogs.confirm({
+     message: "Delete {} bookmarks?",
+     confirm: "Delete",
+     args: [count],
+   });
+   ```
+
+   Never build the sentence in TypeScript (`` `Speed ${rate}×` ``, `"Speed " + rate`): a translator can only translate a whole template, and word order differs between languages. Named arguments work too: `osd.show("{name} is ready", { name })`.
+
+`plugin.i18n.locale` tells which language this run uses, for what is not text (a date: `date.toLocaleDateString(plugin.i18n.locale)`). There is no `t()` function and no event when the language changes: it never changes while the player runs.
+
+#### Text that mixes words and data
+
+Some text is neither a fixed declaration nor a window Slint can build: a menu item "Track 2 (opus)", a ComboBox model whose first item is "No Audio" and the rest track names, an OSD message whose reason is itself a sentence, a list of file names. For these, make a **text value** with `plugin.i18n.text(source, args)` (SDK 1.5.11, player 0.4.3) and pass it where a string would go. It is plain data, not a translation: the player translates `source` with the plugin's catalog and fills in the arguments when it shows it.
+
+```ts nocheck
+const { text, list } = plugin.i18n;
+
+// A menu item with data (the menu merges by the English "Track 2 (opus)").
+plugin.commands.add({
+  id: `track-${n}`,
+  path: ["@audio", "Audio Track", text("Track {} ({})", [n, codec])],
+  run,
+});
+
+// A [string] model: fixed words and data in one list.
+picker.set({ labels: [text("No Audio"), ...tracks.map((t) => text("Track {} · {}", [t.id, t.title]))] });
+
+// An argument that is a sentence of its own.
+await plugin.osd.show("Download failed: {}", [text("Connection timed out")]);
+
+// Items joined the language's way: "a.glsl, b.glsl", "a.glsl、b.glsl".
+await plugin.osd.show("Removed missing shaders: {}", [list(missing)]);
+
+// A message of several parts, each translated: "Added: 3, duplicates skipped: 2".
+await plugin.osd.show(list([text("Added: {}", [added]), text("duplicates skipped: {}", [skipped])], "clauses"));
+```
+
+Arguments are data (strings and numbers, shown as they are) unless they are text values themselves, which are translated too, to any depth (8 levels). `list(items, style)` joins with the interface language's separator: `"list"` (`, ` / `、`), `"clauses"` (`, ` / `，`), `"semicolons"`, `"sentences"` (`. ` / `。`) or `"lines"`.
+
+A text value is accepted wherever the player shows a plugin's text:
+
+| Where | Notes |
+| --- | --- |
+| `commands.add` `title`, `path` segments, `reason`; `Command.set({ reason })` | not a `list`; the menu merges by the English rendering |
+| `osd.show(value)`, `OsdPanel.set(value)`, and as their `args` | a text value as the message carries its own args |
+| `dialogs.confirm` `message`, `detail`, `confirm`, `cancel`, `checkbox` | `args` fills only the string ones |
+| file dialog `title`; `saveFile` `fileName` | a string `fileName` is data; `text("Playlist.m3u8")` is translated |
+| window, panel and settings page properties, where Slint has `string` | at any depth: `[string]` models, struct fields |
+| `TimelineLayer.set` mark titles, `subtitles.load({ title })` | a plain string stays data |
+| a resolver's failure: `throw plugin.i18n.error("The ROM file was not found.")` | shown translated as the open's failure and `player.state.error` |
+
+`extract` collects the `source` of every `text(…)` and `error(…)` call (literals, `?:` branches, `as const` tables), whether called as `plugin.i18n.text` or destructured. Write the source as a literal, never `` text(`Track ${n}`) ``. A source made only of placeholders and punctuation (`"{} ({})"`, `"{0}: {1}"`) is collected like any other: languages differ in punctuation too (Chinese writes `"{}（{}）"`, `"{0}：{1}"`), and a translator who keeps it as it is simply copies it.
+
+**Text that leaves the player.** What the plugin copies to the clipboard or writes to a file is not shown by the player. For that only, `plugin.i18n.resolve(value)` returns the translated string (with the same catalog the player uses): `clipboard.writeText(resolve(list(lines, "lines")))`. Never use it for the interface: a string resolved in TypeScript and then shown would hide the sentence from `check`, and the interface takes text values directly.
+
+**OSD panel lines that must fit.** `OsdPanel.set(value, args, { maxColumns })` cuts each line after translation (a Chinese, Japanese or Korean character is two columns), so the plugin does not measure translated text.
+
+#### Languages
+
+The player's interface languages, and the locale code that names a language's catalog file and is `plugin.i18n.locale` in a run:
+
+| Code | Language | Shown in the menu as |
+| --- | --- | --- |
+| `en` | English (source language) | English |
+| `zh-Hans` | Simplified Chinese | 简体中文 |
+| `ja` | Japanese | 日本語 |
+| `ko` | Korean | 한국어 |
+| `de` | German | Deutsch |
+| `fr` | French | Français |
+| `es` | Spanish | Español |
+
+A plugin may ship any subset; a `.po` file named after a code not in this table is reported by `i18n check` and never read by the player.
+
+#### Files
+
+```text
+locales/
+  messages.pot     every text to translate (written by vestra-plugin i18n extract)
+  zh-Hans.po       Simplified Chinese
+  de.po            German …
+```
+
+One `<lang>.po` per language you provide, named by its locale (the codes in Languages; English is the source and has none). They are ordinary gettext files: any `.po` editor (Poedit, Lokalize, Weblate, a text editor) works. `vestra-plugin build` compiles them into `dist/locales/<lang>.json`, which the player reads; during development (`--plugin <dir>`) the player reads the `.po` files directly.
+
+#### Commands
+
+```sh
+vestra-plugin i18n extract                # write locales/messages.pot, update every locales/<lang>.po
+vestra-plugin i18n extract --locale de    # start a new language
+vestra-plugin i18n check                  # coverage and problems; fails on stale catalogs
+```
+
+`extract` finds every `@tr` in the `.slint` files, the texts given to the calls above (literals, both branches of a `?:`, and `as const` tables, through the TypeScript type checker), and the manifest's display fields. It keeps existing translations, adds new texts untranslated, and moves texts that disappeared to the end of each `.po` as obsolete (`#~`), so a text that comes back keeps its translation. Comments you write yourself stay where they are (SDK 1.5.13): lines before the header (`# Reviewed by … on 2026-10-25`, `# Translator: …`) and `# ` comments on an entry. A plural entry gets exactly as many `msgstr[n]` lines as the file's `Plural-Forms` has `nplurals`: one for Japanese, Korean and Simplified Chinese (an empty `msgstr[1]` left from an older SDK is removed), two for the others.
+
+`check` reports per language how much is translated, translations that lost or changed a placeholder (keep every `{…}` exactly as in the English; reorder with `{0}`, `{1}` only where the English has them), plural forms missing, a stale `messages.pot`, and text that cannot be translated: a sentence composed in TypeScript, a value that is not a literal, Chinese or other non-English source text, and Slint text without `@tr`. These are warnings, except that `i18n check` fails (exit code 1, SDK 1.5.12) when `messages.pot` is out of date or a `.po` lacks some of its messages: run `extract` and commit the result, so CI catches a forgotten `extract`. `vestra-plugin check` prints the same lines when the plugin has a `locales/` folder; none of them fails `check` or a build.
+
+A note for translators goes in a comment that starts with `TRANSLATORS:` right before the text (in TypeScript on the property or the call, or on an entry of an `as const` table (SDK 1.5.12); in Slint on the line above the `@tr`); `extract` copies it into the files.
+
+```ts nocheck
+const REASONS = {
+  // TRANSLATORS: the download took longer than 30 seconds.
+  timeout: "Connection timed out",
+  dns: "Server not found",
+} as const;
+```
+
+#### Machine translations and review
+
+A translation made by a machine (or a language model) is marked as such until a person who knows the language has checked it, so that a reader of the file can tell which entries nobody has looked at yet.
+
+- **Flag each machine-translated entry `x-machine`**, in the entry's `#,` line before its `msgid` (next to `fuzzy`, separated by a comma: `#, fuzzy, x-machine`):
+
+  ```po
+  #. The button that adds one to the count.
+  #: ui/counter.slint:12
+  #, x-machine
+  msgid "Add {}"
+  msgstr "{} hinzufügen"
+  ```
+
+  The flag is only for people. The player and the SDK read `fuzzy` alone (a fuzzy entry is left out of the catalog) and ignore every other flag, so an `x-machine` entry is compiled and shown like any other. `i18n extract` keeps the flag with the translation, also when the text becomes obsolete (`#~`).
+- **A review of the whole file goes in a header comment**: a line before the `msgid ""` header, such as `# Reviewed by an AI reviewer on 2026-10-25` or `# Reviewed by Jane Doe on 2026-10-25 (menus and settings)`. `extract` keeps lines before the header (SDK 1.5.13). An automatic review does not replace a human one: it leaves the `x-machine` flags in place.
+- **A human reviewer removes the flag.** Someone who knows the language reads each entry, corrects what is wrong and then deletes that entry's `x-machine` (from `#, fuzzy, x-machine` only `x-machine`; remove the `#,` line when nothing is left). An entry still flagged has not been reviewed: `grep -c x-machine locales/de.po` counts what is left. When the whole file is done, the header comment names the reviewer and the date.
+
+Translations written by a person from the start carry no flag.
+
+#### Tests
+
+`startPlugin(activate, { directory, locale: "zh-Hans" })` loads `locales/zh-Hans.po` and makes the test host show what a user of that language sees:
+
+```ts nocheck
+const { host, plugin, stop } = await startPlugin(activate, { directory, locale: "zh-Hans" });
+assert.equal(plugin.i18n.locale, "zh-Hans");
+assert.deepEqual(host.command("counter").display.path, ["工具", "计数器…"]);
+assert.deepEqual(host.osd, ["计数：1"]); // osd.show("Count: {}", [1])
+```
+
+`command.display` is the menu as shown (`display.reason` the shown reason), `host.osd`, `host.osdPanel` and `host.confirmTexts` the shown messages, `host.fileDialogs` the file dialogs' titles and file names, window and panel `props` the property values with their text values shown, `host.translate(text, args)` any text (a string or a text value). The declared English stays in `command.declaration` and `host.sent(...)`. Without `locale`, the plugin's own texts show in English as declared, but the player's own texts (core action OSD messages, menu titles and reasons) stay in Simplified Chinese, as in SDK 1.5.8 and older, so existing tests keep passing; pass `locale: "en"` to see the player in English.
+
+#### Limits
+
+- The language changes only at the next start of the player.
+- Plurals have two forms (1 and everything else). For a language with more forms (Russian, Arabic, Polish) the player does not ship a translation.
+- Numbers in templates print as JavaScript writes them (`1.5`), not in the language's own format.
+- A text the player cannot find in the catalog shows in English; so does a plugin's text on a player before 0.4.3, which also shows templates without filling them in. Set `"minPlayerVersion": "0.4.3"` in the manifest of a plugin that relies on templates or text values (older players run an older SDK, which has no `plugin.i18n.text`).
+- Text values have limits on arguments, list items, nesting and bytes (Text values); a property value's limits (Property values) count a text value as the string it becomes.
+
+## How-to: Migrate a plugin to English source text
+
+For plugins written before SDK 1.5.9 whose texts are in one language (Chinese, for the plugins built into Vestra Player). After the migration every text is English in the source, and the old texts become the first translation. The behaviour stays the same: a user with the same language sees exactly the texts as before. Read Translate a plugin first; this page is the checklist.
+
+Needs player 0.4.3 or later: set `"minPlayerVersion": "0.4.3"` in `manifest.json`.
+
+#### 1. Menus: English paths
+
+Before:
+
+```ts nocheck
+plugin.commands.add({ id: "snapshot", path: ["视频", "截图", "保存当前画面…"], run: save });
+```
+
+After:
+
+```ts nocheck
+plugin.commands.add({ id: "snapshot", path: ["@video", "Snapshot", "Save Current Frame…"], run: save });
+```
+
+- The player's menus: `@open`, `@playback`, `@subtitles`, `@video`, `@audio`, `@screen`, `@settings` (or their keys `Open`, `Playback`, `Subtitles`, `Video`, `Audio`, `Screen`, `Settings`). Its own submenus `Playback ▸ Speed` and `Playback ▸ Seek` keep the player's words too. The old Chinese titles of these menus (视频, 播放 ▸ 速度 …) still work, so an unmigrated plugin lands in the same menus meanwhile.
+- **Shared submenus merge by the English words.** When another plugin puts items into the same submenu, both must write it identically. Submenu keys in use lists the English keys the player and its built-in plugins use; reuse those, and ask before inventing a new shared one.
+- Title case for menu items ("Save Current Frame…"), an ellipsis `…` when the item opens a window or asks something.
+- Dynamic items (tracks, devices, presets) whose titles are data (a file name, a device name) stay data: they are not translated. Items whose titles come from a fixed list are text: put the list in an `as const` table so `extract` finds them:
+
+  ```ts nocheck
+  const RATES = [
+    { id: "half", title: "0.5×" },
+    { id: "double", title: "2×" },
+  ] as const;
+  ```
+
+- `order`, `group`, `radio`, `bindings` do not change. Saved user key bindings are kept: they are stored by plugin and command id, not by path.
+
+#### 2. Slint: `@tr`
+
+Before:
+
+```slint
+Button { text: "恢复默认"; }
+Text { text: root.count + " 个文件"; }
+```
+
+After:
+
+```slint
+Button { text: @tr("Restore Defaults"); }
+Text { text: @tr("{n} file" | "{n} files" % root.count); }
+```
+
+Wrap every literal a user reads (`text`, `title`, `placeholder-text`, `tip`, default values of properties shown as text). Do not concatenate in Slint either: `"[" + a + "]"` becomes `@tr("[{}]", a)`.
+
+#### 3. Sentences built in TypeScript
+
+The plugin may no longer build a user-visible sentence in TypeScript. Three ways out, in this order of preference:
+
+**Into the Slint file.** When a window shows it, let the window build it from data:
+
+```ts nocheck
+// Before: TypeScript composes the tooltip.
+panel.bind(() => ({ tipBack: `后退 ${step} 秒 (${key})` }));
+// After: TypeScript passes data; Slint has text: @tr("Back {} s ({})", root.step, root.key)
+panel.bind(() => ({ step, key }));
+```
+
+**A template with arguments**, for the OSD and dialogs:
+
+```ts nocheck
+// Before
+plugin.osd.show(`播放速度：${rate}x`);
+plugin.dialogs.confirm({ message: `删除 ${n} 个书签？`, confirm: "删除" });
+// After
+plugin.osd.show("Speed: {}x", [rate]);
+plugin.dialogs.confirm({ message: "Delete {} bookmarks?", confirm: "Delete", args: [n] });
+```
+
+Arguments are data and are not translated. When an argument would itself be a word from a fixed set (a palette name, "on"/"off"), write one whole template per value instead, so each is translated as a sentence:
+
+```ts nocheck
+// Before
+plugin.osd.show(`配色：${theme === "vestra" ? "Vestra 深色" : "Vestra 浅色"}`);
+// After: both branches are found by extract
+plugin.osd.show(theme === "vestra" ? "Palette: Vestra Dark" : "Palette: Vestra Light");
+```
+
+**A text value** (SDK 1.5.11), when the words and the data cannot be separated into a Slint file or one template: a menu item with a number, a `[string]` model, a sentence made of translated parts, a list.
+
+```ts nocheck
+const { text, list } = plugin.i18n;
+// Before: the old Chinese, or English that a Chinese user then saw
+plugin.commands.add({ id, path: ["@audio", "Audio Track", `Track ${n} (${codec})`], run });
+tune.bind(() => ({ trackLabels: ["关闭字幕", ...names] }));
+plugin.osd.show("Download failed: {}", [english(reason)]);
+plugin.osd.show("Removed missing shaders: {}", [missing.join("、")]);
+// After
+plugin.commands.add({ id, path: ["@audio", "Audio Track", text("Track {} ({})", [n, codec])], run });
+tune.bind(() => ({ trackLabels: [text("Subtitles Off"), ...names] }));
+plugin.osd.show("Download failed: {}", [text(REASONS[reason])]);
+plugin.osd.show("Removed missing shaders: {}", [list(missing)]);
+```
+
+The table of where text values are accepted is in Translate a plugin. A resolver's failure: `throw plugin.i18n.error("The ROM file was not found.")`. Text for the clipboard or a file: `plugin.i18n.resolve(value)`, never for the interface.
+
+**Status texts as data.** A text that a window shows depending on state (`"正在载入…"`, `"没有音轨"`) becomes a state value (`loading: true`) that the Slint file turns into words.
+
+Error messages that come from the player or the SDK (`error.message`) are not the plugin's text: showing them as they are is fine, but do not put them into a template of your own.
+
+#### 4. The manifest
+
+`name`, `punchline`, `description` and `tags` are English; their translations go in the same `.po` files (`extract` collects them). The plugin manager and the store show them translated (`PluginInfo.display`).
+
+#### 5. Write `zh-Hans.po` from the old text
+
+```sh
+vestra-plugin i18n extract --locale zh-Hans   # locales/messages.pot and an empty locales/zh-Hans.po
+```
+
+Then fill every `msgstr` with the text the plugin showed before. That text **is** the translation; copy it exactly, including punctuation and spacing, so users see no change. Placeholders stay as in the English: `msgid "Speed: {}x"` → `msgstr "播放速度：{}x"`. A plural entry in Simplified Chinese needs only `msgstr[0]`. A `git diff` of the migration shows each old text next to its new English.
+
+#### 6. Check
+
+```sh
+vestra-plugin i18n extract    # again after every source change
+vestra-plugin i18n check      # until it prints nothing but the coverage line
+```
+
+`check` finds what is left: Chinese text in TypeScript or Slint, Slint text without `@tr`, sentences composed in TypeScript, values it cannot read, translations whose placeholders differ.
+
+#### 7. Tests
+
+- Assertions on declarations now see English: `command.declaration.path` is what the code declared.
+- To check what a Chinese user sees, start with `locale: "zh-Hans"` and assert on `command.display`, `host.osd`, `host.confirmTexts`; the old expected strings usually stay as they were.
+- `startPlugin` without `locale` plays English for the plugin's texts but keeps the player's own messages (core actions, refusals) in Chinese, as before 1.5.9. Pass `locale` to get the player's English.
+
+```ts nocheck
+const { host, stop } = await startPlugin(activate, { directory, locale: "zh-Hans" });
+assert.deepEqual(host.command("snapshot").display.path, ["视频", "截图", "保存当前画面…"]);
+```
+
+#### Before you hand it in
+
+- [ ] No user-visible Chinese (or other non-English) text left in `.ts` and `.slint` files.
+- [ ] Every Slint text in `@tr`; no sentence composed in TypeScript.
+- [ ] `locales/messages.pot` up to date, `locales/zh-Hans.po` complete (`check`: `zh-Hans: N/N translated`).
+- [ ] Shared submenus use the agreed English keys.
+- [ ] No `i18n-ignore` left on text that only waited for text values (SDK 1.5.11): menu items with data, `[string]` models, nested reasons, lists.
+- [ ] `minPlayerVersion` is `0.4.3`; `vestra-plugin check`, `build` and `test` pass.
+
+## How-to: Test a plugin
+
+**Goal:** tests that run with `npm test` on any machine, without the player, and check what a user would see: the menu items, the window's values, the on-screen messages and what happens when the player refuses a call.
+
+`@vestra-player/sdk/testing` runs the plugin against TestHost, a fake player in memory that speaks the real protocol, so the SDK's own logic (revisions, conditional commits, recovery after lost replies) runs as it does in the player. Only the player side is simplified: there is no decoding, no Slint rendering and no native window. A window is a record of its properties and callbacks, and a source is a set of facts the test chooses.
+
+The tests live in `tests/*.test.ts` and use `node:test`; `vestra-plugin test` (the `test` script of Getting started) runs them. Import `@vestra-player/sdk/testing` only there, never in the plugin itself.
+
+#### The shape of a test
+
+The test of the Bookmark example: it prepares the source before the plugin starts, opens the window from its command, fires two Slint callbacks and checks the window and the playback position.
+
+```ts
+import assert from "node:assert/strict";
+import test from "node:test";
+import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+import activate from "../main.ts";
+
+test("mark the position, then jump back to it", async () => {
+  const host = new TestHost();
+  host.openElsewhere("/movie.mp4");
+  host.setSource({ duration: 600, position: 42 });
+  const { stop } = await startPlugin(activate, {
+    directory: new URL("..", import.meta.url),
+    host,
+  });
+
+  await host.command("bookmark.open").run();
+  const window = host.window("bookmark");
+  window.emit("mark");
+  await host.settle();
+  assert.equal(window.props.label, "Bookmark: 42.0 s");
+
+  host.setSource({ position: 300 }); // playback moves on
+  window.emit("jump");
+  await host.settle();
+  assert.equal(host.source.position, 42);
+  await stop();
+});
+```
+
+Every test follows the same five steps:
+
+1. **Start** the plugin with startPlugin(activate, { directory }). It reads `manifest.json` in `directory` (from `tests/`, `new URL("..", import.meta.url)`), so the declared capabilities apply: a call that needs an undeclared one fails with `capability`, as in the player. It resolves once activation and every registration made during it are done, and rejects when the player would fail the activation (`activate` throws, or a registration made during it fails, for example with `limit`, `conflict` or `invalid`).
+2. **Act** the way the user or another plugin would (below).
+3. **Wait** with `await host.settle()`.
+4. **Assert** on what the host recorded.
+5. **Stop** with `await stop()`: the plugin is disposed as when the player stops it (scopes released, stores flushed) and the host's temporary files are removed. Each test creates its own host.
+
+`startPlugin` also returns `plugin`, the object `activate` received, to call the API directly (`plugin.player.state`). Its options: `host` (a host you prepared before activation, as above), `dataDirectory` (an existing folder as `plugin.dataDirectory`, to test a restart), `locale` (play another interface language, see Translate a plugin), and `id` with `capabilities` to start without a `manifest.json`.
+
+#### Act like the user
+
+| To simulate | Call |
+| --- | --- |
+| choosing a menu item | `await host.command(id).run()`; rejects like the player when the command is disabled or busy |
+| pressing a key | `await host.press("Ctrl+B")`; `host.press("Delete", { panel: true })` while the plugin's panel has focus |
+| a control in a window | `host.window(id).emit(callback, ...args)` (the id is the file name: `ui/picture.slint` is `picture`) |
+| closing a window with its title-bar button | `host.window(id).userClose()` (runs the window's `onClose`, unlike the plugin's own `close()`) |
+| a control in the mounted panel | `host.mounted().emit(callback, ...args)` |
+| answering a dialog | before the action: `host.dialogAnswers.push(["/media/movie.mkv"])` for a file dialog, `null` for Cancel, `{ confirmed: true, checked: false }` for `dialogs.confirm` |
+| another plugin calling `player.next()` | `await host.step("next")` |
+
+`press` follows the player's binding table: the panel's bindings first when `panel` is true, then the global ones, the player's own commands before the plugin's. A disabled command lets the key go on to the next command bound to it (SDK 1.5.12, as player 0.4.3). `press` resolves with what the key did:
+
+- `"ran"`: the first enabled command bound to the key ran;
+- `"reason"`: only disabled commands hold the key, and the first one with a `reason` showed it on the OSD (it is in `host.osd`) and ate the key;
+- `"passed"`: only disabled commands without a reason hold it; the key goes on to the focused control and nothing runs.
+
+It rejects when nothing is bound to the key or the command it would run is busy. User overrides preset in `host.bindings.overlay` apply, and `host.conflicts` lists keys that several commands declare.
+
+```ts
+import assert from "node:assert/strict";
+import test from "node:test";
+import { startPlugin } from "@vestra-player/sdk/testing";
+import activate from "../main.ts";
+
+test("the key does nothing while no video is open", async () => {
+  const { host, stop } = await startPlugin(activate, {
+    directory: new URL("..", import.meta.url),
+  });
+  assert.equal(await host.press("Ctrl+B"), "reason");
+  assert.deepEqual(host.osd, ["Open a video first"]);
+
+  host.openElsewhere("/movie.mp4");
+  await host.settle();
+  assert.equal(await host.press("Ctrl+B"), "ran");
+  assert.deepEqual(host.conflicts, []);
+  await stop();
+});
+```
+
+#### Simulate the player
+
+The test decides what the player is doing:
+
+- `host.openElsewhere(path, phase?)`: the user or another plugin opened a source (a new source id, then `phase`, `"ready"` by default). Calls the plugin made against the old state now fail with `stale`.
+- `host.setSource({ phase, position, duration, paused, audioTracks, … })`: the state changed (the user paused, playback reached the end). Before `startPlugin`, it presets the source the plugin finds at activation.
+- `host.setMainWindow({ fullscreen, videoArea })`, `host.setAppearance(theme)`, `host.setPackages(list)`: the main window, the colour scheme, the installed plugins changed.
+- Preset data the player would return: `host.stats` (`player.stats()`), `host.chapters`, `host.clipboard.text`, `host.secrets`, `host.systemInfo`; `host.tools.handle("ffprobe", (args) => ({ stdout }))` makes a tool available and answers its runs.
+
+#### Inject failures
+
+`host.handle(method, fn)` replaces the player's answer to one protocol method until `host.reset(method)`. The handler gets the request parameters and returns the reply, or throws:
+
+- `throw new HostError(code, message)`: the player refuses; the plugin's call rejects with that `code` (one of the codes in the PluginError table).
+- `throw new Error(…)`: the reply is lost, and the SDK runs its recovery path.
+
+Method names are the protocol's (`"processing.replace"`, `"system.openPath"`, `"clipboard.writeText"`): `host.calls` lists every request in order, which shows the method an action uses, and `host.sent(method)` the parameters of one method's requests.
+
+```ts
+import assert from "node:assert/strict";
+import test from "node:test";
+import { HostError, startPlugin } from "@vestra-player/sdk/testing";
+import activate from "../main.ts";
+
+test("a refused change is shown and can be retried", async () => {
+  const { host, stop } = await startPlugin(activate, {
+    directory: new URL("..", import.meta.url),
+  });
+  host.openElsewhere("/movie.mp4");
+  await host.command("picture").run();
+  host.handle("processing.replace", () => {
+    throw new HostError("unsupported", "no video stream");
+  });
+  host.window("picture").emit("adjust", "gamma", 20);
+  await host.settle();
+  assert.match(String(host.window("picture").props["status"]), /^Picture settings failed/);
+
+  host.reset("processing.replace");
+  host.window("picture").emit("retry");
+  await host.settle();
+  assert.equal(host.window("picture").props["status"], "Picture settings applied");
+  await stop();
+});
+```
+
+#### Wait before asserting
+
+`await host.settle(ms?)` waits until no request is in flight and the SDK's follow-up update passes ran; with `ms` it also waits that long, so that debounces and timers due by then fire (`host.settle(400)` is past `storage.json`'s 300 ms debounce). Call it after every action that makes the plugin talk to the player, before asserting. `command(id).run()` and `press` already wait.
+
+`settle` waits only for calls to the player. Work the plugin does on its own (reading or parsing a file, a child process, a network request) can finish after `settle` returns on a loaded machine; poll the value you assert on instead:
+
+```ts nocheck
+window.emit("load-file"); // the plugin reads and parses the file itself
+for (let i = 0; i < 100 && window.props["status-text"] !== expected; i++)
+  await host.settle(20);
+assert.equal(window.props["status-text"], expected);
+```
+
+#### What to assert on
+
+- **Windows and panels:** `host.window(id).props` and `.visible`, `host.mounted().props`. Property names are the Slint (kebab-case) names: `canMark` is `can-mark`.
+- **Commands:** `host.command(id).state` (`enabled`, `checked`, `busy`, `reason`), `.declaration` (the English path and bindings as declared), `.display` (the menu as shown).
+- **Messages:** `host.osd` (every message shown, oldest first), `host.osdPanel`, `host.confirms` and `host.confirmTexts` (confirmation dialogs), `host.fileDialogs`.
+- **Playback and processing:** `host.source` (`position`, `paused`, `loop`, …), `host.processing`, `host.subtitles`, `host.jobs`, `host.exports`.
+- **Anything else the plugin sent:** `host.sent(method)`; `host.system.opened`, `host.clipboard`, `host.tools.calls` for the system services.
+
+The host checks what the player checks: the command limits, the property value limits and the menu ids are enforced with the player's numbers, and processing values are validated with the player's ranges (an out-of-range `filter.set` ends in `failed` with `invalid`). Export jobs advance one step on every state query (`queued`, `running`, `completed`).
+
+#### Test a restart
+
+Copy `host.dataDirectory` after the first run and pass it as `dataDirectory` to the second, to check what the plugin stored and restores; the example is on startPlugin, and Remember a window's state between runs is a plugin that needs it.
+
+Every member of `TestHost` is in the @vestra-player/sdk/testing reference.
+
+## How-to: Publish a plugin
+
+**Goal:** your plugin appears in the player's plugin store, where users install, update and roll it back.
+
+The store reads the official plugin repository, [vestrasys/vestra-player-plugins](https://github.com/vestrasys/vestra-player-plugins). Every change to it is a pull request to its `main` branch, and **a merge is a release**: there are no beta channels, and CI, the user's rollback and revocation are the safety net. Every plugin in it is a third-party plugin; only the plugins built into the player are official. The repository's [README](https://github.com/vestrasys/vestra-player-plugins#contributing-a-plugin) and [CONTRIBUTING](https://github.com/vestrasys/vestra-player-plugins/blob/main/CONTRIBUTING.md) hold the full rules; this page is the author's path through them.
+
+#### Two ways in
+
+- **Registered** (the usual way): the source stays in your own public GitHub repository, and you register it with one file in the repository's `registry/`. CI builds the package from the commit you name, as Flathub does.
+- **Hosted**: the source lives in the repository's `plugins/<name>/`, and every change is a pull request there. It needs a maintainer's agreement: open an issue first.
+
+> [!IMPORTANT]
+> Building registered plugins from source is not implemented yet. The registration format, the id rule and the owner check are final and checked by CI, but a registration pull request cannot be merged until the build lands (the repository's README shows the status).
+
+#### 1. Prepare the package
+
+From the plugin folder:
+
+```sh
+npx vestra-plugin check   # the manifest and a strict type check
+npx vestra-plugin test    # tests/*.test.ts, see Test a plugin
+npx vestra-plugin pack    # dist/ and <id>-<version>.vxp
+```
+
+Next to `manifest.json` the store needs:
+
+- the display fields in the manifest: `name`, `author`, `punchline`, `description`, `tags`, `license`, `sourceUrl`, optionally `icon`, and `minPlayerVersion` when the plugin needs a newer player than the first one (Manifest has the rules and the version table);
+- `README.md` (what the plugin does, how to use it, what it needs, its limits) and `CHANGELOG.md`, at most 256 KiB each: the store shows both;
+- tests under `tests/` that pass (Test a plugin);
+- only the capabilities the plugin uses: the store lists them on the plugin's page.
+
+#### 2. Choose the id
+
+The id is `<owner>.<name>`, where `<owner>` is the GitHub user or organization that owns the source repository (for a hosted plugin, the owner recorded in the repository's `plugins/owners.toml`), compared without case: `https://github.com/someone/cool-visualizer` publishes ids that start with `someone.`. Letters, digits, `.`, `-` and `_` only.
+
+- `vestra.` is reserved for the player's built-in plugins.
+- An id is unique in the repository, also against a hosted plugin's and also with different case.
+- A changed id is a new plugin to the store: the old id's version history is not carried over.
+
+#### 3. Register the plugin
+
+Push the plugin to your public repository (it may live in a subdirectory) and note the full 40-character id of the commit to publish; a tag such as `v1.0.0` is good practice, but the registration pins the commit. Then fork the plugin repository and add `registry/<id>.toml`:
+
+```text
+# registry/someone.cool-visualizer.toml
+repository = "https://github.com/someone/cool-visualizer"
+commit = "3f2a9c1d4b5e6f708192a3b4c5d6e7f8091a2b3c"
+path = "."            # optional, default "."
+owners = ["someone"]
+```
+
+| Key | Rule |
+| --- | --- |
+| file name | the plugin id plus `.toml`; equals `id` in the manifest |
+| `repository` | `https://github.com/<owner>/<repo>`, no trailing `/` or `.git`; `<owner>` is the id's prefix |
+| `commit` | the full 40-digit lowercase commit id to build |
+| `path` | the folder that holds `manifest.json`, relative, no `..` |
+| `owners` | the GitHub logins allowed to change or remove this file later; must include you |
+
+No other keys. `npm ci && npm run registry` in the plugin repository checks the file.
+
+A hosted plugin instead adds its folder under `plugins/` (manifest, sources, `tests/`, `README.md`, `CHANGELOG.md`) and its owner to `plugins/owners.toml`, after the maintainers agreed in the issue; `npm run plugin -- check <name>` (and `test`, `pack`) run the checks there.
+
+#### 4. Open the pull request
+
+Title it `Add someone.cool-visualizer` (or `Update someone.cool-visualizer to 1.2.0`) and fill in the pull request checklist. On the pull request:
+
+- **Registry owners** checks that you are in `owners` of a new registration, or already an owner of the one you change. It runs the base branch's script and never runs your code.
+- **CI** validates the file and runs the publish flow without publishing; for a hosted plugin it also type checks, tests and packs the plugin on macOS, Windows and Linux.
+- **Review:** a maintainer reads the source at the registered commit (for an update, the diff since the previous one) and merges, or answers in the pull request.
+
+After the merge, the repository's publish workflow builds the package, releases it as `<id>-v<version>`, signs the index and deploys it; the store shows the plugin at its next refresh.
+
+#### Update, withdraw, revoke
+
+- **Update:** bump `version` in the manifest, add a `CHANGELOG.md` entry, commit, and open a pull request that changes `commit` (a hosted plugin: the pull request with the change). A version is published once and never rebuilt: a change without a new version does not reach users, and a version is never reused or lowered.
+- **Owners:** after the first merge only an owner listed on `main` may change or remove the registration, including the list of owners; a maintainer can step in for an abandoned one.
+- **Withdraw:** an owner opens a pull request that deletes the registration file. The plugin drops out of the next index, so the store no longer offers it or checks it for updates; copies already installed stay installed (revocations still reach them), and the released packages stay downloadable.
+- **Revoke:** for a version that is broken or harmful, an owner asks a maintainer for an entry in the repository's `revoked.json`: the plugin id, the versions (`1.2.0`, or a range such as `>=1.0.0 <1.2.0`) and a reason of up to 500 characters, shown to users. Entries are never removed or edited once merged, so fix a mistake with a new version. The store disables an installed version that matches, tells the user why, and offers the fixed version when there is one; a user who enables it again is asked to confirm the risk first.
+
+#### What users see in the store
+
+The store shows the newest version's manifest fields, so what you write there is the plugin's page:
+
+- **The list**: name and version, author and repository, the punchline. Search covers the name, id, author, punchline and tags; the list can be filtered by tag and sorted by name or by the date of the newest version. There are no download counts.
+- **The plugin's page**: the icon, name, author, punchline and the buttons (install, update, roll back, uninstall). Three tabs show the README, the changelog and the version history (version, release date, `minPlayerVersion`, and whether the version is current, incompatible or revoked; an older compatible version can be installed from there). A side column shows the version, the date, the license, a link to `sourceUrl` and the capabilities in plain words, the risky ones highlighted (the wording is the "Shown in the store as" column of Capabilities), with a fixed note that capabilities limit only the player API, not file or network access.
+- **Before installing**, the user confirms a dialog that lists the capabilities; an update that adds capabilities lists the new ones. A plugin whose every version needs a newer player shows "needs Vestra Player x.y.z or later" instead of an install button.
+- **The README** is rendered as Markdown; relative links and images resolve against the README's own address, and remote images are shown for the official repository.
+
+## Guideline: Interface guidelines
+
+These are the rules the player's built-in plugins follow for their windows, panels and messages. Follow them and your plugin looks like part of the player. They assume you know the five surfaces from Windows, panels, settings pages, dialogs and the OSD; token names, sizes, fonts, icons and widgets are listed in Theme.
+
+All sizes are logical pixels (Slint `px`).
+
+#### Choose the smallest surface
+
+- **Feedback is an OSD message, not a window.** Confirm what just happened with osd.show ("Bookmark added", a new volume, a new speed). Do not open a dialog to say that something succeeded: the player's own snapshot command saves at once and shows a message; only "Save As…" asks.
+- **Errors are messages too.** A failed load or a failed action shows one sentence in the OSD; in a window the user is working in, a failure state is drawn in `Theme.danger`.
+- **No permanent text over the video.** Nothing sits above the video, and diagnostic numbers are not always on: show them in an OSD info block (osd.panel) behind a command with a check mark, off by default (the player's "Playback Info", Tab, works this way).
+- **A dialog only for a real question** (before something destructive) or a path (the system file dialogs). See Choosing a surface.
+
+#### Theme
+
+- **Use `Theme` tokens for every colour**, never a colour value: hard-coded colours do not follow the user's palette (`vestra` dark or `vestra-light`). `Theme.danger` is for failure states and destructive buttons, `Theme.playing` for what is playing now, `Theme.accent` for hover, "on" and selection marks, `Theme.accent-fill` for progress-like fills (sliders, levels).
+- **Over the video, use the OSD's colours.** The video area is dark in both palettes, so text and icons drawn on it (a backdrop, an overlay) are white (`#ffffff`) on a translucent dark plate (`#0b0a10c4`), not `Theme.text`, which is dark in `vestra-light`.
+- **A check mark on an accent background is white**, in both palettes.
+- **Do not set a font family.** Every window uses the system UI font, and Slint falls back per character (CJK included); a fixed family breaks scripts it lacks. For code or aligned numbers use `Theme.font-mono`.
+- **Use the four font sizes only**: `Theme.font-xs` (tiny labels), `Theme.font-body` (body text, lists, times), `Theme.font-tab` (tabs, menus), `Theme.font-title` (window and tab titles). Times and counters use tabular digits (`font-feature: tnum`) so they do not jitter.
+- **Do not change `Palette.color-scheme`.** The player switches the `std-widgets.slint` controls between their dark and light colours with the palette.
+
+#### Icons
+
+- **Icons come from `@vestra/icons.slint`.** Never use a font character as an icon (✓ › ▲ ▼ ▾ × ▶): each system's font draws it differently.
+- **Icon colours follow the state**: normal `Theme.text` (or `Theme.text-dim` for small icons), hover or on `Theme.accent`, pressed `Theme.accent-press`, disabled `Theme.icon-disabled`.
+- An icon is drawn in its own box, which is its default size; keep it, so rows and buttons line up with the player's.
+- For an icon of your own, draw it the same way: lines only, never filled, round caps and joins, 1.5px wide (1.25px for icons of 12px or less), kept inside the box.
+
+#### Controls
+
+- **Use the player's widgets** from `@vestra/widgets.slint`: `Button` (21px high; `small` 18px), `Slider` (the bottom bar style, or `panel: true` in tool windows), `ToolTipArea`, `UrlInputRow`. They take their sizes and colours from `Theme`. Other controls come from `std-widgets.slint`.
+- **Control sizes are tokens**: `Theme.button-height`, `Theme.button-primary-height` (the main action at the bottom of a dialog), `Theme.button-small-height` (a "Default" button in a row), `Theme.input-height`, `Theme.checkbox-row-height`, `Theme.label-height`, `Theme.form-row-gap`, `Theme.dialog-padding`.
+- **Corners**: `Theme.radius-control` for buttons, rows, hover plates and tooltips; `Theme.radius-panel` for menus, floating layers and larger plates.
+- **Icon buttons have no separators between them.** Hover and press light a rounded plate behind the icon (`Theme.hover-bg`, `Theme.press-bg`).
+- **Explain icon buttons with a tooltip** (`ToolTipArea`), and put long values (a full path) in a tooltip instead of a line of text.
+
+#### Tool windows
+
+- **No heading inside the window.** The title bar already shows the window's `title`.
+- **Theme sizes throughout**: buttons and inputs 21px, form rows 24–26px apart, padding 8–14px, body text `Theme.font-body`.
+- **Adjustments apply at once.** A window that changes picture, sound or subtitles has no "Apply" or "OK": every change takes effect while the user moves the control, and each row has its own "Default" button that resets it. Keep the slider responsive while dragging (the slider guide).
+- **Status and error text is one sentence**, written as English source text and translated like every other text (Translate a plugin). Never show debugging details: task ids, revisions, generations, stack traces.
+- **Closing a tool window does not undo its effect.** The window is a way to change a setting, not the setting's owner.
+
+##### Small adjustment windows
+
+The player's picture, audio and subtitle tools share one layout; a window of the same kind uses it too:
+
+| Part                          | Size and style                                                                                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Window                        | 301 wide, at most 320 × 280; background `Theme.bg-bar`; content 8 from the left and right edges (285 usable)                                |
+| Tabs (if any)                 | 31 high, 74 wide, text `Theme.font-tab` in `Theme.text-dim`; the current tab in `Theme.text` with a short `Theme.accent-fill` line under it |
+| Page                          | background `Theme.bg-panel`                                                                                                                 |
+| Row                           | 24 high: label 65 wide, right-aligned, `Theme.font-body`; `Slider` with `panel: true`, 154 × 12; a small "Default" button, 41 × 18          |
+| Toggle buttons (flip, rotate) | 46 × 22; choice buttons 51 × 22 (69 wide for longer labels)                                                                                 |
+
+##### Dialog-like windows
+
+- **A link input is `UrlInputRow`**: the input with **Open** and **Cancel**, Enter accepts and Escape cancels, no history list. The player's own link windows (Open URL, the playlist's Add URL, the plugin store) all use it.
+- **Group the fields** of a longer form (storage, format and size, range…) with labels in a right-aligned left column; the main action is a primary button (`Theme.button-primary-height`) at the bottom.
+- The standard close keys close every tool window; you cannot and need not handle them.
+
+#### Panels
+
+- **A sidebar panel has no heading of its own.** The player shows its title in the sidebar's tab strip when there are two or more panels; with one panel there is no strip.
+- **No status or path lines in a panel.** Messages go to the OSD; a full path is a tooltip on its row.
+- **Show state with colour, not words.** As in the player's playlist: what is playing in `Theme.playing` (with a 2px bar at the left), what was played in `Theme.text-played`, the selection on `Theme.selected-bg`. A failed item gets the `failed` icon at the end of its row and an OSD message.
+- **Lists are plain**: single-line rows, background `Theme.bg-list`, no cards, no stripes, no rounded rows; scroll bars come from `std-widgets.slint` so they follow the palette.
+- **Commands of a panel go into its right-click menu**, made of the plugin's commands (panel.showMenu); see Menus.
+- **The bottom bar is icons only**: no text buttons, no source path, no status text (the source name is in the window title, status is an OSD message).
+
+#### Text
+
+- **Every visible text is English source text** that the player translates (Translate a plugin). Write short, plain sentences; one sentence per status or error.
+- **Leave room for longer languages.** German and French texts are usually longer than English; a Chinese, Japanese or Korean character is about one font size wide, a Latin letter about half. Let labels and buttons grow with their text (layouts, `preferred-width`; the `Button` widget does) instead of fixing widths to the English text.
+- **Mixed scripts must render without boxes.** That is why you use the system font (above): the player falls back per character to the system's fonts (on Windows also to a bundled CJK font) (Theme).
+- **Data is not translated.** File names, track names and device names show as they are.
+
+#### Check your plugin
+
+- Switch the palette (Settings ▸ Appearance) with your windows open: everything should follow at once.
+- Switch the interface language (Settings ▸ Language, used from the next start) to German and to Japanese, and look for clipped or overlapping text.
+- Compare your tool window with the player's Picture Adjustments window: same row heights, same buttons, same slider.
+
+## Guideline: Menu guidelines
+
+The player has one menu, opened with a right click on the video. There is no menu button in the window and no menu bar at the top of the screen, so every command a user may look for is in this menu or in a panel's right-click menu. It is merged from the commands of every plugin and the player's own; these rules keep the result one menu instead of a pile of plugins.
+
+How paths merge, how `order` and `group` sort items and how a key finds its command are explained in Commands, menus and key bindings. Menu ids, the shared menu keys, the binding syntax and the keys the system takes first are listed in Commands. The declaration itself is CommandOptions.
+
+#### Organize by what the user does
+
+- **Put a command where its subject is, not under your plugin's name.** A video filter goes into Video, a subtitle tool into Subtitles, an open-something command into Open. A plugin that brings a domain of its own gets a submenu named after the domain, not after the plugin (the NES plugin's Emulator).
+- **Before adding an item, look for an existing one.** Every command the player and its built-in plugins add, with its menu path and default key, is listed in Built-in commands. Do not add a second entry for something the player already does, and do not scatter one feature over several menus.
+- **Top level is for frequent, direct commands**: opening files, closing, fullscreen and the entries that show a window or panel. Everything else goes into a submenu of its domain.
+- **No "File" or "View" menu.** Commands that open something go into Open ▸; commands that show a window or panel sit directly at the top level.
+
+#### The top level
+
+The top level as the player ships it (shortcuts in the Windows notation; the menu shows each system's own):
+
+```text
+Open File…                    Ctrl+O, F3   group open
+Open ▸
+Close                         F4
+Reopen Current/Last File      Ctrl+Y
+Copy to Clipboard ▸
+────────────────────────────────────────
+Playback ▸                                 group domain
+Subtitles ▸
+Video ▸
+Audio ▸
+Emulator ▸
+────────────────────────────────────────
+Toggle Fullscreen             Enter        group screen
+Screen ▸
+────────────────────────────────────────
+Playlist  ✓                   F6           group windows
+Playback Info  ✓              Tab
+Playback Properties…          Ctrl+F1
+Vestra Player AI…
+Plugin Store…
+────────────────────────────────────────
+Settings ▸
+────────────────────────────────────────
+About Vestra Player…          F1
+────────────────────────────────────────
+Quit                          Cmd+Q        group exit
+```
+
+A top-level item uses the group and the `order` range of its kind:
+
+| Group                  | `order` | For                                                                              |
+| ---------------------- | ------- | -------------------------------------------------------------------------------- |
+| `open`                 | 100–199 | Opening and closing sources                                                      |
+| `domain` (the default) | 200–699 | Domain submenus: Playback, Subtitles, Video, Audio, and a new domain of your own |
+| `screen`               | 700–799 | Fullscreen and the window's size and placement                                   |
+| `windows`              | 800–899 | Items that show a window or a panel (a check mark when it toggles one)           |
+| `exit`                 | 900–999 | Quit                                                                             |
+
+Keep a group's orders contiguous: `group` only draws a separator between neighbours of different groups, so an item whose order falls into another group's range splits that group in two.
+
+#### Inside a built-in menu
+
+- **Name the menu by its id**: `["@video", "Blur"]`. The seven built-in menus (Open, Playback, Subtitles, Video, Audio, Screen, Settings) stay where they are whatever you put in them.
+- **Without an `order`, your item goes to the end** of the menu, after the player's own items, which is usually right for a plugin. To sit next to a related player item, give an `order` near that item's; the player's items use 100 and up, in the order listed in Built-in commands, and the ranges per menu are at CommandOptions.order.
+- **Group related items** with a `group` of your own, so a separator sets them apart from the player's items.
+- **Playback ▸ Speed and Playback ▸ Seek are the player's.** You can add to them; their titles stay the player's.
+
+#### Shared submenus
+
+- **Write a shared submenu exactly as the menu keys list does.** Menus merge by the English words of the path: `["@playback", "Chapters and Bookmarks", …]` joins the existing submenu, `["@playback", "Bookmarks", …]` makes a second one. The keys are in Commands.
+- **A new submenu that other plugins should use is a new menu key**: ask the player's maintainers to register it instead of inventing it in one plugin, so it appears in the list.
+- **A submenu's title is translated by the catalog of the plugin that declares its first command**; your own submenu therefore needs its words in your catalog.
+- **Menu paths are written with `▸`** (U+25B8) in documentation and messages, never `▶`, which many systems draw as an emoji.
+
+#### Titles
+
+- **Title Case**, short: "Save Current Frame", "Show Marks on Seek Bar". A menu is as wide as its longest title in the user's language; a CJK character counts about twice a Latin letter, and German or French titles are longer than English, so a long title widens the whole menu.
+- **End with `…`** (one character, U+2026) when the item opens a window or asks something before acting ("Adjust Sync…", "Plugin Store…"); no `…` when it acts at once.
+- **A toggle has a check mark** (`checked: true | false`, as "Show Subtitles"). **Mutually exclusive choices are radio items** (`radio: true`) in one group: speeds, loop modes, snapshot formats, palettes.
+- **Do not put key names in a title.** The menu shows each item's binding on the right, in the system's notation.
+- **Dynamic items are data.** Track names, device names, file names and bookmarks are shown as they are, not translated. Cap long dynamic lists well below the command limit (Limits): the player shows at most 50 chapters and ends the list with "More Chapters… (N in all)".
+- **Keep unavailable items, disabled, with a reason** (`enabled: false` and `reason`) instead of removing them; remove an item only when it can never apply here (the player's Picture-in-Picture item exists only where the system supports it). An empty dynamic list shows one disabled item that says so ("No Audio Tracks").
+
+#### A panel's right-click menu
+
+- **A panel's commands go into its own right-click menu** (panel.showMenu), not into the main menu: it looks the same and is made of the plugin's own commands. Commands that make sense only in the panel have no `path` there.
+- **Keys that act on the panel's content** (Enter to play, Delete to remove) are bindings with `focus: "panel"`: they win over the global meaning of the same key while the panel has focus, and give it back when it loses focus. That is intended, not a conflict.
+- The player's playlist is the model: its list menu, its Add and Sort buttons and its panel keys; its panel keys are at the end of Built-in commands.
+
+#### Default bindings
+
+A default binding is optional. Users rebind every command (Settings ▸ Keyboard Shortcuts…) and can turn all defaults off (Settings ▸ Ignore Default Shortcuts), so give one only to a command people repeat often.
+
+- **Pick an unused key.** Check Built-in commands, which lists every default binding of the player and its built-in plugins. Two commands with the same key are not an error, but only one of them runs (the user's choice, then the player's own commands, then the plugin loaded first), so a colliding default simply does nothing for the user.
+- **Write `Ctrl`, not `Cmd`**, for a binding that works on both systems: on macOS `Ctrl+X` fires for both ⌃X and ⌘X.
+- **Avoid the keys the system takes first**, the standard close keys among them, as defaults.
+- **The right mouse button opens the menu** and is not a binding input; the other video-area mouse inputs are.
+- **A typed symbol is its own key**: `>` is not `Shift+.`, so `.` and `>` can do different things.
+- **Remember that bindings belong to the main window.** They do not fire while a tool window or the Options window has focus (Focus and keyboard).
+
+## Reference: Manifest
+
+`manifest.json` sits at the root of the plugin directory and of the package. The player and every `vestra-plugin` command check it against the same rules: an unknown field, an unknown capability, a field that breaks its rule, or a path that leaves the package (symbolic links included) is refused.
+
+```json
+{
+  "id": "me.bookmark",
+  "version": "0.1.0",
+  "apiVersion": "vestra/1",
+  "entry": "main.ts",
+  "capabilities": ["commands", "ui.window"],
+  "name": "Bookmark",
+  "punchline": "Mark a moment and jump back to it.",
+  "minPlayerVersion": "0.4.3"
+}
+```
+
+#### Fields
+
+**Kind**: *required* fields every plugin has (`version` may come from `package.json` at build time); *display* fields are optional and shown by the plugin store and the plugin manager (player 0.2.0); *optional* changes how the player loads the plugin.
+
+| Field | Kind | Rule |
+| --- | --- | --- |
+| `id` | required | 1–128 bytes of ASCII letters, digits and `.`, `-`, `_`. Ids `vestra` and `vestra.…` (any case) belong to the player's built-in plugins; installing one fails with `reserved`. A plugin in the official plugin repository is named `<GitHub user or organization>.<plugin>`; `vestra-plugin check` only hints at a missing prefix. |
+| `version` | required in the package | `x.y.z`, three whole numbers. `vestra-plugin build` writes it into `dist/manifest.json` from `--version`, the manifest or `package.json`. |
+| `apiVersion` | required | `vestra/1`. |
+| `entry` | required | Path of the entry module inside the package: `.ts` while developing, `.js` after `build`. |
+| `capabilities` | required | Capabilities from Capabilities, each at most once. |
+| `name` | display | 1–64 characters, one line, no leading or trailing white space. English; translated with the plugin's catalog. |
+| `author` | display | 1–64 characters, one line. |
+| `punchline` | display | One-line summary, 1–120 characters. English; translated. |
+| `description` | display | Plain text, 1–2000 characters; line breaks allowed. English; translated. |
+| `tags` | display | At most 8 tags, each 1–24 characters on one line, unique ignoring case. English; translated. |
+| `icon` | display | Package path of a PNG or JPEG (by content), at most 512 KiB and 1024 pixels per side; 256×256 recommended. |
+| `readme` | display | Package path of a UTF-8 `.md` file of at most 256 KiB, shown on the store page. Default: `README.md` when the package has one. |
+| `changelog` | display | The same rules; default `CHANGELOG.md` when present. |
+| `sourceUrl` | display | An `https:` address of at most 2048 bytes. |
+| `license` | display | 1–64 characters, preferably an SPDX expression such as `MIT`. |
+| `minPlayerVersion` | optional | `x.y.z`: the oldest player that loads the plugin (compared with `plugin.app.version`, three numbers). An older player refuses it with `versionMismatch` ("requires Vestra Player ≥ x.y.z") before it reads anything else, so a manifest with newer fields fails with that, not with an unknown field. See Player versions. |
+
+- `name`, `punchline`, `description` and `tags` are English source text; the player shows them translated with the plugin's own catalog (Translate a plugin) through PluginInfo.
+- An `icon`, `readme` or `changelog` that is named but missing is refused. `vestra-plugin build` copies them (and a default `README.md` or `CHANGELOG.md`) into the package: the README is the plugin's page in the store, so write it for users.
+- A call to a member whose capability is not declared fails with code `capability` (Capabilities).
+
+#### Player versions
+
+The SDK's major version follows the plugin API: every 1.x release implements `apiVersion` `vestra/1`, minor releases only add to it, and a breaking change gets a new `apiVersion` and a new major version. Some additions also need a newer player. A plugin that uses one sets `minPlayerVersion` to the highest version it needs; an older player then refuses it with `versionMismatch` instead of failing at the first call.
+
+The table lists the API whose documentation names a player version, newest last:
+
+| Player | API that needs it or changed with it |
+| --- | --- |
+| 0.2.0 | Plugin.dataDirectory, MarkdownRef, Ui.markdown, PackageManifest, Packages.validateArchive |
+| 0.3.0 | CommandOptions, MENU_IDS |
+| 0.4.0 | ThemeId |
+| 0.4.1 | PluginError, FileResolverOptions, PackageCandidate.install, PluginWarning.code, Packages.validate |
+| 0.4.2 | Resolvers.fileTypes, Resolvers.onFileTypesChange |
+| 0.4.3 | CommandOptions.path, PropValue, View.set, Appearance.setLanguage, TemplateArgs, Text, ConfirmOptions.args, OsdPanel.set, OsdPanelOptions.maxColumns, Osd.show |
+| 0.5.1 | SlotState.reason, Panel.setInteraction, PlaybackStats.presentedFps |
+
+The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
+
+`@vestra-player/sdk/runtime` is the player's own entry point and is not covered by these rules. What changed in each SDK release is in the [CHANGELOG](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md).
+
+## Reference: Capabilities
+
+A plugin lists what it may do in the manifest's `capabilities` (Manifest). A call to a member whose capability is missing fails with code `capability`; nothing else is checked at run time, and capabilities limit only the player API, not the file system or the network (a plugin is a Node.js process). The store shows the capabilities to the user before installing, in the words of the "Shown in the store as" column; the highlighted ones reach outside the plugin's own features.
+
+| Capability | Opens | Also needs | Shown in the store as | Highlighted |
+| --- | --- | --- | --- | --- |
+| `producer.av` | Player.openStream | `playback.control` | Provide audio and video it generates itself |  |
+| `playback.read` | Player.state, Player.refresh, Player.stats, Player.chapters, Player.audioDevices, Timeline.marks | — | Read what is playing and the position |  |
+| `playback.control` | Player.open, Player.setPaused, Player.seek, Player.setRate, Player.restart, Player.close, Player.scrub, Player.setOutput, Player.provideSequence, Player.next, Player.previous, Player.addAudioTrack, Player.selectAudioTrack, Player.step, Player.setStepSeek, Player.setLoop, Player.setAudioDevice, Power.preventSleep | — | Open media, control playback, keep the computer awake |  |
+| `source.resolve` | Resolvers.add | — | Resolve online video addresses |  |
+| `events` | Player.onChange, Subtitles.onChange, Timeline.onChange, MainWindow.onChange, Appearance.onChange, PanelSlot.onChange, Panel.onChange, BackdropSlot.onChange, Resolvers.onFileTypesChange | — | Receive playback changes as they happen |  |
+| `commands` | Commands.add, Host.run | — | Add menu commands and shortcuts |  |
+| `ui.window` | Windows.create | — | Open tool windows |  |
+| `ui.mount` | Panels.mount, Panels.bottom, Panels.sidebar, Panels.backdrop, PanelSlot.onChange, Panel.onChange, BackdropSlot.onChange | — | Show panels in the bottom bar, the sidebar or behind the video |  |
+| `ui.dialog` | Dialogs.confirm, Dialogs.openFile, Dialogs.openFiles, Dialogs.openDirectory, Dialogs.saveFile | — | Show file pickers and confirmations |  |
+| `plugins.manage` | Packages.validate, Packages.validateArchive, Packages.rollback, Packages.setEnabled, Packages.uninstall | — | Install, uninstall and disable other plugins | yes |
+| `processing.video` | Plugin.video.filter, Plugin.video.view, Plugin.video.render | `playback.read` | Process the picture (filters, shaders) |  |
+| `processing.audio` | Plugin.audio.filter | `playback.read`, `events` | Process the sound |  |
+| `subtitles.read` | Subtitles.state, Subtitles.onChange, Subtitles.refresh | — | Read subtitles |  |
+| `subtitles.control` | Subtitles.select, Subtitles.load, Subtitles.remove, Subtitles.setStyle | — | Load and change subtitles |  |
+| `media.read` | MediaCapture.capture, Snapshot.export | `media.control` | Take snapshots and export clips |  |
+| `media.control` | MediaCapture.capture, Snapshot.export | `media.read` | Take snapshots and export clips |  |
+| `ui.osd` | Osd.show, Osd.panel | — | Show messages on the video |  |
+| `clipboard` | Clipboard.readText, Clipboard.writeText, Clipboard.writeImage | — | Read and write the clipboard | yes |
+| `window.control` | MainWindow.setVideoArea, MainWindow.setAlwaysOnTop, MainWindow.setCursorAutoHide, MainWindow.setPictureInPicture | — | Adjust the main window (size, on top, picture-in-picture) |  |
+| `bindings.manage` | Bindings.list, Bindings.set, Bindings.reset, Bindings.onChange | — | Change all shortcuts | yes |
+| `timeline.marks` | Timeline.layer | — | Show marks on the progress bar |  |
+| `ui.drop` | Drops.provide, Panel.onDrop | — | Receive files dropped on the player |  |
+| `ui.settings` | Settings.page, Settings.show | — | Add pages to the Options window |  |
+| `ui.theme` | Appearance.set, Appearance.setLanguage | — | Change the player's palette |  |
+| `secrets` | Secrets.get, Secrets.set, Secrets.delete | — | Store sign-in details in the system keychain | yes |
+
+**Also needs** applies to every member of the row: declare those capabilities as well. A few members or options need one more, documented at the member:
+
+- video.filter also needs `events`.
+- A `processed` snapshot or export (MediaCapture) also needs `playback.read` and `subtitles.read`.
+- A file resolver (Resolvers.add with file types) also needs `producer.av`.
+- Without `events`, Player.state is read at start and after the plugin's own operations, and `onChange` listeners do not fire for changes made elsewhere.
+
+#### Without a capability
+
+A member not in the table needs no capability: `plugin.tools`, `plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui` (images and Markdown), `plugin.i18n`, reading window.state, appearance.theme and packages.list. The table is `CAPABILITY_INFO`, which tests can import from `@vestra-player/sdk/testing` to check a manifest (CAPABILITY_INFO).
+
+## Reference: Limits
+
+The player bounds what one request may cost it. The limits are guards against runaway plugins, not sizes to aim for: a plugin that needs to come close to one usually needs a different design (send the rows near the view, not the whole list). The SDK checks the same limits before it sends a request, so a plugin's own tests hit them too (TestHost enforces them). A name in code style is a constant you can import from `@vestra-player/sdk/testing`.
+
+#### Commands
+
+A command added past a limit fails with code `limit` (its `ready` rejects; during activation, activation fails). Commands already registered are unaffected, and disposing one frees its slot at once.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `COMMAND_LIMITS.perPlugin` | 160 | Commands one plugin instance may have at the same time. |
+| `COMMAND_LIMITS.total` | 1024 | Commands of every plugin plus the player's own, together. |
+
+#### Property values
+
+One value written to a window, panel or settings page property (View.set, View.bind or an initial property). A value over a limit is refused whole with code `limit`; the property keeps what it showed.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `UI_VALUE_LIMITS.depth` | 8 | Nesting depth; the value itself is depth 0. |
+| `UI_VALUE_LIMITS.values` | 16384 | Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one. |
+| `UI_VALUE_LIMITS.arrayRows` | 4096 | Rows of one array. |
+| `UI_VALUE_LIMITS.stringBytes` | 65536 (64 KiB) | UTF-8 bytes of one string or object field name. |
+| `UI_VALUE_LIMITS.textBytes` | 1048576 (1 MiB) | UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included. |
+
+#### Text values
+
+One Text or TextList, with everything nested in it. A text over a limit fails with code `invalid`.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `TEXT_LIMITS.depth` | 8 | Nesting depth of texts and lists; the value itself is depth 0. |
+| `TEXT_LIMITS.nodes` | 1024 | Texts, lists and arguments in all, the value itself included. |
+| `TEXT_LIMITS.args` | 16 | Arguments of one text. |
+| `TEXT_LIMITS.items` | 256 | Items of one list. |
+| `TEXT_LIMITS.stringBytes` | 4096 (4 KiB) | UTF-8 bytes of a source text or a string argument. |
+
+#### Markdown
+
+plugin.ui.markdown and its image downloads. A failed or oversized image shows its alt text; the call does not fail for it. The number of images per document and of blocks shown are on `Ui.markdown`.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| textBytes | 262144 (256 KiB) | Text bytes. |
+| imageBytes | 4194304 (4 MiB) | Bytes of one downloaded image. |
+| imageTimeoutMs | 10000 (10 s) | Download time per image. |
+| redirects | 5 | Redirects followed per image. |
+| concurrency | 4 | Downloads at once, per plugin. |
+| cacheBytes | 33554432 (32 MiB) | Cache size per plugin. |
+| cacheMaxAgeMs | 86400000 (24 h) | An address is fetched again after this long. |
+
+#### On-screen display
+
+Counted on the text as shown, after translation and with its arguments filled in. A text over a limit fails with code `invalid`: osd.show rejects, OsdPanel.set reports to `Scope.onError`. Font sizes and placement are at Osd.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `OSD_LIMITS.messageChars` | 200 | Characters of one `osd.show` message (200; at least 1 that is not white space). Line breaks are shown as spaces. |
+| `OSD_LIMITS.panelLines` | 32 | Lines of the information block (`OsdPanel.set`). |
+| `OSD_LIMITS.panelBytes` | 4096 (4 KiB) | UTF-8 bytes of the information block. |
+| `OSD_LIMITS.minColumns` | 8 | The smallest `OsdPanelOptions.maxColumns`. |
+| `OSD_LIMITS.maxColumns` | 1000 | The largest `OsdPanelOptions.maxColumns`. |
+
+#### Secrets
+
+plugin.secrets. A name or value out of its rule fails with code `invalid`; a new name beyond the count fails with `limit`.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `SECRET_LIMITS.nameChars` | 64 | Characters of a name (64, at least 1), each one of `a-z`, `0-9`, `.`, `_` and `-`. |
+| `SECRET_LIMITS.valueBytes` | 1024 (1 KiB) | UTF-8 bytes of a value. |
+| `SECRET_LIMITS.names` | 256 | Different names one plugin may have stored at the same time. |
+
+#### Messages
+
+Every request a plugin sends travels as one protocol line. The plugin's side refuses a longer one with code `limit` before sending it; property values meet their own limits first.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MESSAGE_LIMIT` | 1048576 (1 MiB) | The longest message a plugin may send the player, in UTF-8 bytes of one protocol line with its newline (1 MiB). The player stops a plugin that writes a longer one, so the plugin's side refuses such a request before sending it: it rejects with code `limit`. Property values meet `UI_VALUE_LIMITS` before this. |
+
+#### Render options
+
+RenderSettings; more shaders fail with `invalid`.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| Entries of `RenderSettings.shaders` | 16 | mpv user shaders (`.glsl`): absolute paths of existing files, at most 16, in order. |
+
+#### Limits documented at their API
+
+- Filter chains: the number of nodes across all plugins, one `frameBlend`, and the range of every node's parameters, at VideoFilter; the audio delay at AudioFilter.
+- Generated streams: frame sizes and sample values at StreamFrame; a frame that breaks them ends the stream with `invalid`.
+- Manifest fields: Manifest.
+
+## Reference: Commands, menus and bindings
+
+The names to look up while declaring a command with plugin.commands.add. How menus merge and how a key finds its command is explained in Commands, menus and key bindings; where a command should go is in Guidelines: menus.
+
+#### Menu paths
+
+A command's `path` is a list of 1 to 8 segments in English source text, the last one the item itself: `["@video", "Snapshot", "Copy Snapshot"]`. This documentation writes a path with `▸`: **Video ▸ Snapshot ▸ Copy Snapshot**. The `▸` is notation only; a segment never contains it.
+
+- Paths merge by these English texts (their **keys**), whatever the interface language, so commands whose paths start with the same keys share a submenu.
+- The first segment may name a built-in menu by id (`@video`) or by key (`Video`). Only the first segment is read as an id; an unknown id (`@view`) or an id with nothing after it fails with `invalid`.
+- A segment that contains data is a Text; it merges by its English rendering.
+
+#### Built-in menus
+
+| First segment | Or its key |
+| --- | --- |
+| `@open` | `Open` |
+| `@playback` | `Playback` |
+| `@subtitles` | `Subtitles` |
+| `@video` | `Video` |
+| `@audio` | `Audio` |
+| `@screen` | `Screen` |
+| `@settings` | `Settings` |
+
+Players before 0.3.0 show `@video` as a menu of its own; players up to 0.4.2 titled these menus in Chinese, where only the id form reaches them. The fixed orders of the built-in menus and of the player's own items are on CommandOptions.order.
+
+#### Submenu keys in use
+
+The submenus that exist already, by key path. Write the same keys to add a command to one of them; a near-synonym makes a second submenu.
+
+| Key path | Declared by |
+| --- | --- |
+| Playback ▸ Speed | the player |
+| Playback ▸ Seek | the player |
+| Open ▸ Recently Played | `vestra.history` |
+| Playback ▸ A-B Loop | `vestra.marks` |
+| Playback ▸ A-B Loop ▸ Loop Count | `vestra.marks` |
+| Playback ▸ Chapters and Bookmarks | `vestra.marks` |
+| Playback ▸ Playlist | `vestra.playlist` |
+| Playback ▸ Playlist ▸ Repeat | `vestra.playlist` |
+| Playback ▸ Playlist ▸ When Opening a File | `vestra.playlist` |
+| Playback ▸ Resume Playback | `vestra.history` |
+| Subtitles ▸ Online Subtitles | `vestra.subtitle-online` |
+| Subtitles ▸ Secondary Subtitle | `vestra.subtitles` |
+| Subtitles ▸ Secondary Subtitle ▸ Position | `vestra.subtitles` |
+| Subtitles ▸ Subtitle Style | `vestra.subtitles` |
+| Subtitles ▸ Subtitle Track | `vestra.subtitles` |
+| Subtitles ▸ Sync | `vestra.subtitles` |
+| Video ▸ Aspect | `vestra.video` |
+| Video ▸ Crop/Stretch | `vestra.video` |
+| Video ▸ Deinterlace | `vestra.video` |
+| Video ▸ Deinterlace ▸ Output | `vestra.video` |
+| Video ▸ Framing | `vestra.video` |
+| Video ▸ Image Processing | `vestra.video` |
+| Video ▸ Pixel Shaders | `vestra.video` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping | `vestra.video` |
+| Video ▸ Rotation | `vestra.video` |
+| Video ▸ Snapshot | `vestra.capture` |
+| Audio ▸ Audio Sync | `vestra.audio` |
+| Audio ▸ Audio Track | `vestra.audio` |
+| Audio ▸ Output Device | `vestra.audio` |
+| Audio ▸ Preset | `vestra.audio` |
+| Audio ▸ Processing | `vestra.audio` |
+| Screen ▸ Always on Top | `vestra.window` |
+| Screen ▸ When Playback Starts | `vestra.window` |
+| Settings ▸ Appearance | `vestra.preferences`, `vestra.visualizer` |
+| Settings ▸ Language | `vestra.preferences` |
+| Copy to Clipboard | `vestra.playback` |
+| Emulator | `vestra.nes` |
+
+#### Built-in commands
+
+Every command the player (`host`) and its built-in plugins register when the player starts with nothing open, in menu order; commands outside the main menu (a panel's shortcuts) come last. Items built from content (tracks, recent files, output devices) are not listed. The **Command** column is `<owner>/<id>`, the key under which the user's own bindings are stored. The same list is BUILTIN_COMMANDS, for tests that check your defaults against it.
+
+| Menu item | Default bindings | Command |
+| --- | --- | --- |
+| Open File… | `Ctrl+O`, `F3` | `vestra.playback/open` |
+| Open ▸ Open URL… | `Ctrl+U` | `vestra.playback/open-url` |
+| Open ▸ Open Folder… | `F2` | `vestra.playlist/playlist.open-folder` |
+| Open ▸ Open Subtitle… | `Alt+O` | `vestra.subtitles/load` |
+| Open ▸ Load External Audio… |  | `vestra.audio/audio.load` |
+| Open ▸ Recently Played ▸ (No Entries) |  | `vestra.history/recent.empty` |
+| Open ▸ Recently Played ▸ Remove Invalid Entries |  | `vestra.history/recent.prune` |
+| Open ▸ Recently Played ▸ Clear Entries |  | `vestra.history/recent.clear` |
+| Open ▸ Recently Played ▸ Record Playback History |  | `vestra.history/recent.enabled` |
+| Open ▸ Add Secondary Subtitle… |  | `vestra.subtitles/load-secondary` |
+| Close | `F4` | `host/stop` |
+| Reopen Current/Last File | `Ctrl+Y` | `vestra.playback/reopen` |
+| Copy to Clipboard ▸ File Name |  | `vestra.playback/copy-name` |
+| Copy to Clipboard ▸ Folder Path |  | `vestra.playback/copy-folder` |
+| Copy to Clipboard ▸ Full Path |  | `vestra.playback/copy-path` |
+| Playback ▸ Play/Pause | `Space` | `host/play-pause` |
+| Playback ▸ Previous | `PageUp`, `Mouse:X1` | `host/previous` |
+| Playback ▸ Next | `PageDown`, `Mouse:X2` | `host/next` |
+| Playback ▸ Seek ▸ Previous Frame | `D` | `host/frame-back` |
+| Playback ▸ Seek ▸ Next Frame | `F` | `host/frame-forward` |
+| Playback ▸ Seek ▸ Previous Keyframe | `Ctrl+Shift+ArrowLeft` | `vestra.playback/keyframe-back` |
+| Playback ▸ Seek ▸ Next Keyframe | `Ctrl+Shift+ArrowRight` | `vestra.playback/keyframe-forward` |
+| Playback ▸ Seek ▸ Back 5 s | `ArrowLeft` | `host/seek-backward` |
+| Playback ▸ Seek ▸ Forward 5 s | `ArrowRight` | `host/seek-forward` |
+| Playback ▸ Seek ▸ Back 30 s | `Ctrl+ArrowLeft` | `vestra.playback/backward-2` |
+| Playback ▸ Seek ▸ Forward 30 s | `Ctrl+ArrowRight` | `vestra.playback/forward-2` |
+| Playback ▸ Seek ▸ Back 60 s | `Shift+ArrowLeft` | `vestra.playback/backward-3` |
+| Playback ▸ Seek ▸ Forward 60 s | `Shift+ArrowRight` | `vestra.playback/forward-3` |
+| Playback ▸ Seek ▸ Back 300 s | `Ctrl+Alt+ArrowLeft` | `vestra.playback/backward-4` |
+| Playback ▸ Seek ▸ Forward 300 s | `Ctrl+Alt+ArrowRight` | `vestra.playback/forward-4` |
+| Playback ▸ Seek ▸ Previous Dialogue | `Home` | `vestra.subtitles/dialogue-previous` |
+| Playback ▸ Seek ▸ Next Dialogue | `End` | `vestra.subtitles/dialogue-next` |
+| Playback ▸ Seek ▸ Current Subtitle Start | `Ctrl+Home` | `vestra.subtitles/dialogue-current` |
+| Playback ▸ Seek ▸ Jump to Start | `Backspace` | `vestra.playback/jump-start` |
+| Playback ▸ Seek ▸ Seek Steps… |  | `vestra.playback/time-jump` |
+| Playback ▸ Jump to Time… | `G` | `vestra.playback/jump` |
+| Playback ▸ Speed ▸ Normal | `Z` | `host/rate-normal` |
+| Playback ▸ Speed ▸ Slower 0.1 | `X` | `host/rate-down` |
+| Playback ▸ Speed ▸ Faster 0.1 | `C` | `host/rate-up` |
+| Playback ▸ Speed ▸ 0.5× |  | `vestra.playback/rate-05` |
+| Playback ▸ Speed ▸ 1.5× |  | `vestra.playback/rate-15` |
+| Playback ▸ Speed ▸ 2× |  | `vestra.playback/rate-20` |
+| Playback ▸ Speed ▸ Custom… |  | `vestra.playback/rate-custom` |
+| Playback ▸ Playlist ▸ Add Files… |  | `vestra.playlist/playlist.add` |
+| Playback ▸ Playlist ▸ Add Link… |  | `vestra.playlist/playlist.link` |
+| Playback ▸ Playlist ▸ Add Folder… |  | `vestra.playlist/playlist.add-folder` |
+| Playback ▸ Playlist ▸ Repeat ▸ Off |  | `vestra.playlist/playlist.repeat-none` |
+| Playback ▸ Playlist ▸ Repeat ▸ All |  | `vestra.playlist/playlist.repeat-all` |
+| Playback ▸ Playlist ▸ Repeat ▸ One |  | `vestra.playlist/playlist.repeat-one` |
+| Playback ▸ Playlist ▸ Shuffle |  | `vestra.playlist/playlist.shuffle` |
+| Playback ▸ Playlist ▸ Open List File… |  | `vestra.playlist/playlist.open-list` |
+| Playback ▸ Playlist ▸ Save List… |  | `vestra.playlist/playlist.save-list` |
+| Playback ▸ Playlist ▸ When Opening a File ▸ Open Only That File |  | `vestra.playlist/playlist.open-mode-only` |
+| Playback ▸ Playlist ▸ When Opening a File ▸ Add Similar Files |  | `vestra.playlist/playlist.open-mode-similar` |
+| Playback ▸ Playlist ▸ When Opening a File ▸ Add All Files in the Folder |  | `vestra.playlist/playlist.open-mode-folder` |
+| Playback ▸ Playlist ▸ Fast Advance to Next |  | `vestra.playlist/playlist.fast-advance` |
+| Playback ▸ Playlist ▸ Remember List |  | `vestra.playlist/playlist.remember` |
+| Playback ▸ Playlist ▸ Confirm Before Removing All |  | `vestra.playlist/playlist.confirm-clear` |
+| Playback ▸ Disable Screen Saver While Playing |  | `vestra.playback/prevent-sleep` |
+| Playback ▸ Hide Pointer While Playing |  | `vestra.window/hide-cursor` |
+| Playback ▸ Show Time on Seek Bar Hover |  | `vestra.playback/hover-time` |
+| Playback ▸ Show Thumbnail on Seek Bar Hover |  | `vestra.playback/hover-thumbnail` |
+| Playback ▸ Resume Playback ▸ Don't Resume |  | `vestra.history/resume.off` |
+| Playback ▸ Resume Playback ▸ Resume Automatically |  | `vestra.history/resume.auto` |
+| Playback ▸ Resume Playback ▸ Ask Every Time |  | `vestra.history/resume.ask` |
+| Playback ▸ Resume Playback ▸ Also Remember Audio Files |  | `vestra.history/resume.audio` |
+| Playback ▸ Resume Playback ▸ Clear All Saved Positions |  | `vestra.history/resume.clear` |
+| Playback ▸ Chapters and Bookmarks ▸ Chapter and Bookmark List… | `H` | `vestra.marks/marks.list` |
+| Playback ▸ Chapters and Bookmarks ▸ Add Bookmark | `P` | `vestra.marks/marks.add` |
+| Playback ▸ Chapters and Bookmarks ▸ Previous Bookmark or Chapter | `Shift+PageUp` | `vestra.marks/marks.previous` |
+| Playback ▸ Chapters and Bookmarks ▸ Next Bookmark or Chapter | `Shift+PageDown` | `vestra.marks/marks.next` |
+| Playback ▸ Chapters and Bookmarks ▸ Previous Chapter | `Ctrl+PageUp` | `vestra.marks/marks.previous-chapter` |
+| Playback ▸ Chapters and Bookmarks ▸ Next Chapter | `Ctrl+PageDown` | `vestra.marks/marks.next-chapter` |
+| Playback ▸ Chapters and Bookmarks ▸ Show Marks on Seek Bar |  | `vestra.marks/marks.seekbar` |
+| Playback ▸ A-B Loop ▸ Set Start Point | `[` | `vestra.marks/ab.set-a` |
+| Playback ▸ A-B Loop ▸ Clear Start Point | `{` | `vestra.marks/ab.clear-a` |
+| Playback ▸ A-B Loop ▸ Start Point Back 0.1 s | `Ctrl+[` | `vestra.marks/ab.a-back` |
+| Playback ▸ A-B Loop ▸ Start Point Forward 0.1 s | `Alt+[` | `vestra.marks/ab.a-forward` |
+| Playback ▸ A-B Loop ▸ Set End Point | `]` | `vestra.marks/ab.set-b` |
+| Playback ▸ A-B Loop ▸ Clear End Point | `}` | `vestra.marks/ab.clear-b` |
+| Playback ▸ A-B Loop ▸ End Point Back 0.1 s | `Ctrl+]` | `vestra.marks/ab.b-back` |
+| Playback ▸ A-B Loop ▸ End Point Forward 0.1 s | `Alt+]` | `vestra.marks/ab.b-forward` |
+| Playback ▸ A-B Loop ▸ Move Range Back 0.1 s | `Ctrl+Alt+[` | `vestra.marks/ab.back` |
+| Playback ▸ A-B Loop ▸ Move Range Forward 0.1 s | `Ctrl+Alt+]` | `vestra.marks/ab.forward` |
+| Playback ▸ A-B Loop ▸ Loop Current Chapter or Bookmark Range | `Alt+\` | `vestra.marks/ab.segment` |
+| Playback ▸ A-B Loop ▸ A-B Loop On/Off | `\` | `vestra.marks/ab.toggle` |
+| Playback ▸ A-B Loop ▸ Loop Count ▸ Endless |  | `vestra.marks/ab.count.endless` |
+| Playback ▸ A-B Loop ▸ Loop Count ▸ Once |  | `vestra.marks/ab.count.1` |
+| Playback ▸ A-B Loop ▸ Loop Count ▸ 2 Times |  | `vestra.marks/ab.count.2` |
+| Playback ▸ A-B Loop ▸ Loop Count ▸ 3 Times |  | `vestra.marks/ab.count.3` |
+| Playback ▸ A-B Loop ▸ Loop Count ▸ 5 Times |  | `vestra.marks/ab.count.5` |
+| Playback ▸ A-B Loop ▸ Loop Count ▸ 10 Times |  | `vestra.marks/ab.count.10` |
+| Subtitles ▸ Show Subtitles | `Alt+H` | `vestra.subtitles/show` |
+| Subtitles ▸ Subtitle Track ▸ Off |  | `vestra.subtitles/track-off` |
+| Subtitles ▸ Subtitle Track ▸ Cycle | `Alt+L` | `vestra.subtitles/track-cycle` |
+| Subtitles ▸ Secondary Subtitle ▸ Off |  | `vestra.subtitles/second-off` |
+| Subtitles ▸ Secondary Subtitle ▸ Position ▸ Top |  | `vestra.subtitles/second-position-top` |
+| Subtitles ▸ Secondary Subtitle ▸ Position ▸ Above Main Subtitle |  | `vestra.subtitles/second-position-aboveMain` |
+| Subtitles ▸ Subtitle Style ▸ Bold | `Alt+B` | `vestra.subtitles/bold` |
+| Subtitles ▸ Subtitle Style ▸ Size + | `Alt+PageUp` | `vestra.subtitles/size-up` |
+| Subtitles ▸ Subtitle Style ▸ Size − | `Alt+PageDown` | `vestra.subtitles/size-down` |
+| Subtitles ▸ Subtitle Style ▸ Move Up | `Alt+ArrowUp` | `vestra.subtitles/move-up` |
+| Subtitles ▸ Subtitle Style ▸ Move Down | `Alt+ArrowDown` | `vestra.subtitles/move-down` |
+| Subtitles ▸ Subtitle Style ▸ Reset Position | `Alt+Home` | `vestra.subtitles/move-reset` |
+| Subtitles ▸ Subtitle Style ▸ Shadow |  | `vestra.subtitles/shadow` |
+| Subtitles ▸ Subtitle Style ▸ Opaque Box |  | `vestra.subtitles/box` |
+| Subtitles ▸ Original ASS/SSA Styles |  | `vestra.subtitles/ass-original` |
+| Subtitles ▸ Sync ▸ Earlier 0.5 s | `.` | `vestra.subtitles/sync-earlier` |
+| Subtitles ▸ Sync ▸ Later 0.5 s | `,` | `vestra.subtitles/sync-later` |
+| Subtitles ▸ Sync ▸ Reset | `/` | `vestra.subtitles/sync-reset` |
+| Subtitles ▸ Sync ▸ Adjust Sync… |  | `vestra.subtitles/sync-input` |
+| Subtitles ▸ Online Subtitles ▸ Search and Download Subtitles… |  | `vestra.subtitle-online/search` |
+| Subtitles ▸ Online Subtitles ▸ Online Subtitle Settings… |  | `vestra.subtitle-online/settings` |
+| Subtitles ▸ Reload Subtitles | `Ctrl+Alt+Y` | `vestra.subtitles/reload` |
+| Subtitles ▸ Refresh Subtitle Tracks |  | `vestra.subtitles/refresh` |
+| Subtitles ▸ Subtitle Tuning… |  | `vestra.subtitles/tune` |
+| Subtitles ▸ Subtitle Settings… |  | `vestra.subtitles/settings` |
+| Video ▸ Pixel Shaders ▸ Use Shaders | `Shift+P` | `vestra.video/video.shader.use` |
+| Video ▸ Pixel Shaders ▸ Shader List… |  | `vestra.video/video.shader.list` |
+| Video ▸ Pixel Shaders ▸ Open Shader Folder |  | `vestra.video/video.shader.folder` |
+| Video ▸ Pixel Shaders ▸ Reload Shaders |  | `vestra.video/video.shader.reload` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping ▸ Auto |  | `vestra.video/video.hdr.auto` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping ▸ Off |  | `vestra.video/video.hdr.off` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping ▸ BT.2390 |  | `vestra.video/video.hdr.bt.2390` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping ▸ Hable |  | `vestra.video/video.hdr.hable` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping ▸ Mobius |  | `vestra.video/video.hdr.mobius` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping ▸ Reinhard |  | `vestra.video/video.hdr.reinhard` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping ▸ Clip |  | `vestra.video/video.hdr.clip` |
+| Video ▸ Pixel Shaders ▸ HDR Tone Mapping ▸ Dynamic Peak Detection |  | `vestra.video/video.hdr.peak` |
+| Video ▸ Pixel Shaders ▸ HDR Settings… |  | `vestra.video/video.hdr.settings` |
+| Video ▸ Deinterlace ▸ Cycle | `Ctrl+I` | `vestra.video/video.deinterlace.cycle` |
+| Video ▸ Deinterlace ▸ Auto |  | `vestra.video/video.deinterlace.auto` |
+| Video ▸ Deinterlace ▸ Always |  | `vestra.video/video.deinterlace.on` |
+| Video ▸ Deinterlace ▸ Never |  | `vestra.video/video.deinterlace.off` |
+| Video ▸ Deinterlace ▸ Output ▸ By Frame |  | `vestra.video/video.deinterlace.output.frame` |
+| Video ▸ Deinterlace ▸ Output ▸ By Field (Double Rate) |  | `vestra.video/video.deinterlace.output.field` |
+| Video ▸ Aspect ▸ Keep Aspect Ratio |  | `vestra.video/video.fit.keep` |
+| Video ▸ Aspect ▸ Ignore Aspect Ratio |  | `vestra.video/video.fit.stretch` |
+| Video ▸ Aspect ▸ Fill Window (Crop Excess) |  | `vestra.video/video.fit.fill` |
+| Video ▸ Aspect ▸ Cycle Aspect Ratio | `Shift+F6` | `vestra.video/video.aspect.cycle` |
+| Video ▸ Aspect ▸ Default (Source) |  | `vestra.video/video.aspect.default` |
+| Video ▸ Aspect ▸ 4:3 |  | `vestra.video/video.aspect.0` |
+| Video ▸ Aspect ▸ 16:9 |  | `vestra.video/video.aspect.1` |
+| Video ▸ Aspect ▸ 16:10 |  | `vestra.video/video.aspect.2` |
+| Video ▸ Aspect ▸ 1.85:1 |  | `vestra.video/video.aspect.3` |
+| Video ▸ Aspect ▸ 2.35:1 |  | `vestra.video/video.aspect.4` |
+| Video ▸ Aspect ▸ Custom (x:y) |  | `vestra.video/video.aspect.custom` |
+| Video ▸ Aspect ▸ Custom Aspect Ratio… |  | `vestra.video/video.aspect.edit` |
+| Video ▸ Crop/Stretch ▸ None |  | `vestra.video/video.reframe.none` |
+| Video ▸ Crop/Stretch ▸ Stretch to 4:3 |  | `vestra.video/video.reframe.pad.0` |
+| Video ▸ Crop/Stretch ▸ Stretch to 16:9 |  | `vestra.video/video.reframe.pad.1` |
+| Video ▸ Crop/Stretch ▸ Stretch to 16:10 |  | `vestra.video/video.reframe.pad.2` |
+| Video ▸ Crop/Stretch ▸ Stretch to 1.85:1 |  | `vestra.video/video.reframe.pad.3` |
+| Video ▸ Crop/Stretch ▸ Stretch to 2.35:1 |  | `vestra.video/video.reframe.pad.4` |
+| Video ▸ Crop/Stretch ▸ Crop to 4:3 |  | `vestra.video/video.reframe.crop.0` |
+| Video ▸ Crop/Stretch ▸ Crop to 16:9 |  | `vestra.video/video.reframe.crop.1` |
+| Video ▸ Crop/Stretch ▸ Crop to 16:10 |  | `vestra.video/video.reframe.crop.2` |
+| Video ▸ Crop/Stretch ▸ Crop to 1.85:1 |  | `vestra.video/video.reframe.crop.3` |
+| Video ▸ Crop/Stretch ▸ Crop to 2.35:1 |  | `vestra.video/video.reframe.crop.4` |
+| Video ▸ Crop/Stretch ▸ Reset Position |  | `vestra.video/video.reframe.reset` |
+| Video ▸ Crop/Stretch ▸ Move Left |  | `vestra.video/video.reframe.left` |
+| Video ▸ Crop/Stretch ▸ Move Right |  | `vestra.video/video.reframe.right` |
+| Video ▸ Crop/Stretch ▸ Move Up |  | `vestra.video/video.reframe.up` |
+| Video ▸ Crop/Stretch ▸ Move Down |  | `vestra.video/video.reframe.down` |
+| Video ▸ Framing ▸ Reset Framing | `Numpad5`, `Alt+Backspace` | `vestra.video/video.frame.reset` |
+| Video ▸ Framing ▸ Zoom In | `Numpad9`, `Alt+Plus` | `vestra.video/video.frame.zoom-in` |
+| Video ▸ Framing ▸ Zoom Out | `Numpad1`, `Alt+-` | `vestra.video/video.frame.zoom-out` |
+| Video ▸ Framing ▸ Pan → | `Ctrl+Numpad6`, `Alt+ArrowRight` | `vestra.video/video.frame.right` |
+| Video ▸ Framing ▸ Pan ← | `Ctrl+Numpad4`, `Alt+ArrowLeft` | `vestra.video/video.frame.left` |
+| Video ▸ Framing ▸ Pan ↑ | `Ctrl+Numpad8`, `Alt+ArrowUp` | `vestra.video/video.frame.up` |
+| Video ▸ Framing ▸ Pan ↓ | `Ctrl+Numpad2`, `Alt+ArrowDown` | `vestra.video/video.frame.down` |
+| Video ▸ Framing ▸ Center Frame | `Ctrl+Numpad5` | `vestra.video/video.frame.centre` |
+| Video ▸ Image Processing ▸ Flip Vertically | `Ctrl+P` | `vestra.video/video.flip.vertical` |
+| Video ▸ Image Processing ▸ Flip Horizontally | `Ctrl+Z` | `vestra.video/video.flip.horizontal` |
+| Video ▸ Image Processing ▸ Gaussian Blur | `Ctrl+B` | `vestra.video/video.gaussian` |
+| Video ▸ Image Processing ▸ Sharpen | `Ctrl+R` | `vestra.video/video.sharpen` |
+| Video ▸ Image Processing ▸ Edge Sharpen |  | `vestra.video/video.edge` |
+| Video ▸ Image Processing ▸ Deblock | `Ctrl+H` | `vestra.video/video.deblock` |
+| Video ▸ Image Processing ▸ Deband |  | `vestra.video/video.deband` |
+| Video ▸ Image Processing ▸ 3D Denoise | `Ctrl+N` | `vestra.video/video.denoise.d3` |
+| Video ▸ Image Processing ▸ Gradual Denoise |  | `vestra.video/video.denoise.gradual` |
+| Video ▸ Image Processing ▸ Temporal Denoise | `Ctrl+M` | `vestra.video/video.denoise.temporal` |
+| Video ▸ Image Processing ▸ Frame Doubling |  | `vestra.video/video.frame-blend` |
+| Video ▸ Image Processing ▸ Motion Interpolation |  | `vestra.video/video.interpolation` |
+| Video ▸ Rotation ▸ Cycle | `Alt+K` | `vestra.video/video.rotate.cycle` |
+| Video ▸ Rotation ▸ No Rotation |  | `vestra.video/video.rotate.0` |
+| Video ▸ Rotation ▸ 90° |  | `vestra.video/video.rotate.90` |
+| Video ▸ Rotation ▸ 180° |  | `vestra.video/video.rotate.180` |
+| Video ▸ Rotation ▸ 270° |  | `vestra.video/video.rotate.270` |
+| Video ▸ Snapshot ▸ Save Current Frame | `Ctrl+E` | `vestra.capture/capture.save` |
+| Video ▸ Snapshot ▸ Save Current Frame As… |  | `vestra.capture/capture.saveAs` |
+| Video ▸ Snapshot ▸ Copy Current Frame | `Ctrl+C` | `vestra.capture/capture.copy` |
+| Video ▸ Snapshot ▸ Save Rendered Frame | `Ctrl+Alt+E` | `vestra.capture/capture.saveScreen` |
+| Video ▸ Snapshot ▸ Save Rendered Frame As… |  | `vestra.capture/capture.saveScreenAs` |
+| Video ▸ Snapshot ▸ Copy Rendered Frame | `Ctrl+Alt+C` | `vestra.capture/capture.copyScreen` |
+| Video ▸ Snapshot ▸ Burst… | `Ctrl+G` | `vestra.capture/capture.burst` |
+| Video ▸ Snapshot ▸ Export Clip… |  | `vestra.capture/capture.clip` |
+| Video ▸ Snapshot ▸ Export Tasks… |  | `vestra.capture/capture.tasks` |
+| Video ▸ Snapshot ▸ Capture as PNG |  | `vestra.capture/capture.format.png` |
+| Video ▸ Snapshot ▸ Capture as JPEG |  | `vestra.capture/capture.format.jpeg` |
+| Video ▸ Snapshot ▸ Capture as BMP |  | `vestra.capture/capture.format.bmp` |
+| Video ▸ Snapshot ▸ Include Subtitles in Rendered Frame |  | `vestra.capture/capture.screenSubtitles` |
+| Video ▸ Snapshot ▸ Snapshot Settings… |  | `vestra.capture/capture.settings` |
+| Video ▸ Snapshot ▸ Snapshot Folder… |  | `vestra.capture/capture.folder` |
+| Video ▸ Snapshot ▸ Open Snapshot Folder |  | `vestra.capture/capture.openFolder` |
+| Video ▸ Picture Adjustments… |  | `vestra.video/video.picture` |
+| Video ▸ Reset | `Q` | `vestra.video/video.reset` |
+| Video ▸ Brightness -1% | `W` | `vestra.video/video.brightness.down` |
+| Video ▸ Brightness +1% | `E` | `vestra.video/video.brightness.up` |
+| Video ▸ Contrast -1% | `R` | `vestra.video/video.contrast.down` |
+| Video ▸ Contrast +1% | `T` | `vestra.video/video.contrast.up` |
+| Video ▸ Saturation -1% | `Y` | `vestra.video/video.saturation.down` |
+| Video ▸ Saturation +1% | `U` | `vestra.video/video.saturation.up` |
+| Video ▸ Hue -1% | `I` | `vestra.video/video.hue.down` |
+| Video ▸ Hue +1% | `O` | `vestra.video/video.hue.up` |
+| Audio ▸ Volume + | `ArrowUp`, `Mouse:WheelUp` | `host/volume-up` |
+| Audio ▸ Volume − | `ArrowDown`, `Mouse:WheelDown` | `host/volume-down` |
+| Audio ▸ Mute | `M` | `host/mute` |
+| Audio ▸ Audio Workbench… |  | `vestra.audio/audio.workbench` |
+| Audio ▸ Audio Track ▸ No Audio Tracks |  | `vestra.audio/audio.track.none` |
+| Audio ▸ Audio Track ▸ Cycle Tracks | `Alt+A` | `vestra.audio/audio.track.cycle` |
+| Audio ▸ Audio Track ▸ Stereo |  | `vestra.audio/audio.channels.stereo` |
+| Audio ▸ Audio Track ▸ Left Channel |  | `vestra.audio/audio.channels.left` |
+| Audio ▸ Audio Track ▸ Right Channel |  | `vestra.audio/audio.channels.right` |
+| Audio ▸ Audio Track ▸ Mono Mix |  | `vestra.audio/audio.channels.mono` |
+| Audio ▸ Audio Track ▸ Swap Left and Right |  | `vestra.audio/audio.channels.swap` |
+| Audio ▸ Output Device ▸ No Output Devices |  | `vestra.audio/audio.device.none` |
+| Audio ▸ Equalizer | `Shift+E` | `vestra.audio/audio.equalizer` |
+| Audio ▸ Preset ▸ Flat |  | `vestra.audio/audio.preset.0` |
+| Audio ▸ Preset ▸ Voice |  | `vestra.audio/audio.preset.1` |
+| Audio ▸ Preset ▸ Music |  | `vestra.audio/audio.preset.2` |
+| Audio ▸ Preset ▸ Cinema |  | `vestra.audio/audio.preset.3` |
+| Audio ▸ Audio Sync ▸ 50 ms Earlier | `>` | `vestra.audio/audio.sync.earlier` |
+| Audio ▸ Audio Sync ▸ 50 ms Later | `<` | `vestra.audio/audio.sync.later` |
+| Audio ▸ Audio Sync ▸ Reset | `?` | `vestra.audio/audio.sync.reset` |
+| Audio ▸ Audio Sync ▸ Don't Keep |  | `vestra.audio/audio.sync.keep.none` |
+| Audio ▸ Audio Sync ▸ Keep for This Run |  | `vestra.audio/audio.sync.keep.session` |
+| Audio ▸ Audio Sync ▸ Always Keep |  | `vestra.audio/audio.sync.keep.always` |
+| Audio ▸ Processing ▸ Normalize | `Shift+N` | `vestra.audio/audio.normalize` |
+| Audio ▸ Processing ▸ Crystalizer | `Shift+C` | `vestra.audio/audio.clarity` |
+| Audio ▸ Reset |  | `vestra.audio/audio.reset` |
+| Audio ▸ Show Album Cover for Audio Only |  | `vestra.visualizer/audio-cover` |
+| Emulator ▸ Open NES ROM… |  | `vestra.nes/nes.open` |
+| Emulator ▸ Stop NES |  | `vestra.nes/nes.stop` |
+| Emulator ▸ NES Tools… |  | `vestra.nes/nes.window` |
+| Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11`, `Mouse:LeftDoubleClick` | `host/fullscreen` |
+| Screen ▸ Picture-in-Picture |  | `vestra.window/pip` |
+| Screen ▸ Mini Size | ``` | `vestra.window/mini` |
+| Screen ▸ 0.5× | `1` | `vestra.window/size.0.5` |
+| Screen ▸ 1× | `2` | `vestra.window/size.1` |
+| Screen ▸ 1.5× | `3` | `vestra.window/size.1.5` |
+| Screen ▸ 2× | `4` | `vestra.window/size.2` |
+| Screen ▸ Fit to Video Aspect Ratio | `8` | `vestra.window/fit` |
+| Screen ▸ When Playback Starts ▸ Don't Resize |  | `vestra.window/auto.off` |
+| Screen ▸ When Playback Starts ▸ 0.5× |  | `vestra.window/auto.0.5` |
+| Screen ▸ When Playback Starts ▸ 1× |  | `vestra.window/auto.1` |
+| Screen ▸ When Playback Starts ▸ 1.5× |  | `vestra.window/auto.1.5` |
+| Screen ▸ When Playback Starts ▸ 2× |  | `vestra.window/auto.2` |
+| Screen ▸ When Playback Starts ▸ Fit to Video Aspect Ratio |  | `vestra.window/auto.fit` |
+| Screen ▸ When Playback Starts ▸ Only Once |  | `vestra.window/auto.once` |
+| Screen ▸ Always on Top ▸ Cycle Mode | `Ctrl+T` | `vestra.window/top.cycle` |
+| Screen ▸ Always on Top ▸ Never |  | `vestra.window/top.never` |
+| Screen ▸ Always on Top ▸ Always |  | `vestra.window/top.always` |
+| Screen ▸ Always on Top ▸ While Playing |  | `vestra.window/top.playing` |
+| Screen ▸ Always on Top ▸ While Playing in Fullscreen |  | `vestra.window/top.fullscreen` |
+| Playlist | `F6` | `vestra.playlist/playlist.visibility` |
+| Playback Info | `Tab` | `vestra.info/info.toggle` |
+| Playback Properties… | `Ctrl+F1` | `vestra.info/info.properties` |
+| Vestra Player AI… |  | `vestra.workshop/workshop.open` |
+| Plugin Store… |  | `vestra.store/open` |
+| Settings ▸ Options… | `F5` | `vestra.preferences/options` |
+| Settings ▸ Keyboard Shortcuts… |  | `vestra.hotkeys/keys` |
+| Settings ▸ Mouse… |  | `vestra.hotkeys/mouse` |
+| Settings ▸ Ignore Default Shortcuts |  | `vestra.hotkeys/ignore-defaults` |
+| Settings ▸ Plugin Manager… |  | `vestra.plugins/manage` |
+| Settings ▸ Appearance ▸ Vestra Dark |  | `vestra.preferences/theme.vestra` |
+| Settings ▸ Appearance ▸ Vestra Light |  | `vestra.preferences/theme.vestra-light` |
+| Settings ▸ Appearance ▸ Show Logo When Idle |  | `vestra.visualizer/idle-logo` |
+| Settings ▸ Appearance ▸ Choose Logo Image… |  | `vestra.visualizer/choose-logo` |
+| Settings ▸ Appearance ▸ Restore Default Logo |  | `vestra.visualizer/reset-logo` |
+| Settings ▸ Language ▸ Follow System |  | `vestra.preferences/language.system` |
+| Settings ▸ Language ▸ English |  | `vestra.preferences/language.en` |
+| Settings ▸ Language ▸ 简体中文 |  | `vestra.preferences/language.zh-Hans` |
+| Settings ▸ Language ▸ 日本語 |  | `vestra.preferences/language.ja` |
+| Settings ▸ Language ▸ 한국어 |  | `vestra.preferences/language.ko` |
+| Settings ▸ Language ▸ Deutsch |  | `vestra.preferences/language.de` |
+| Settings ▸ Language ▸ Français |  | `vestra.preferences/language.fr` |
+| Settings ▸ Language ▸ Español |  | `vestra.preferences/language.es` |
+| About Vestra Player… | `F1` | `vestra.info/info.about` |
+| Quit | `Cmd+Q` | `host/quit` |
+| Leave Fullscreen (not in the menu) | `Escape` | `host/exit-fullscreen` |
+| Brief Info (not in the menu) | `Shift+Tab` | `vestra.info/info.brief` |
+| Play (not in the menu) | `Enter`, `P` (panel focus) | `vestra.playlist/playlist.play` |
+| Add Files… (not in the menu) | `Ctrl+I` (panel focus) | `vestra.playlist/playlist.list-add` |
+| Add Folder… (not in the menu) | `Ctrl+O` (panel focus) | `vestra.playlist/playlist.list-add-folder` |
+| Add Link… (not in the menu) | `Ctrl+U` (panel focus) | `vestra.playlist/playlist.list-link` |
+| Remove Selected (not in the menu) | `Delete`, `Backspace` (panel focus) | `vestra.playlist/playlist.remove` |
+| Remove Unselected (not in the menu) | `Ctrl+Delete` (panel focus) | `vestra.playlist/playlist.remove-unselected` |
+| Remove Invalid Items (not in the menu) | `Ctrl+T` (panel focus) | `vestra.playlist/playlist.remove-invalid` |
+| Remove All (not in the menu) | `Alt+Delete` (panel focus) | `vestra.playlist/playlist.clear` |
+| Show in Finder (not in the menu) | `Ctrl+F` (panel focus) | `vestra.playlist/playlist.reveal` |
+| Move to Top (not in the menu) | `Ctrl+Home` (panel focus) | `vestra.playlist/playlist.move-top` |
+| Move Up (not in the menu) | `Ctrl+ArrowUp` (panel focus) | `vestra.playlist/playlist.move-up` |
+| Move Down (not in the menu) | `Ctrl+ArrowDown` (panel focus) | `vestra.playlist/playlist.move-down` |
+| Move to Bottom (not in the menu) | `Ctrl+End` (panel focus) | `vestra.playlist/playlist.move-bottom` |
+| Ascending (not in the menu) | `Ctrl+1` (panel focus) | `vestra.playlist/playlist.sort-ascending` |
+| Descending (not in the menu) | `Ctrl+2` (panel focus) | `vestra.playlist/playlist.sort-descending` |
+| By Title (not in the menu) | `Ctrl+3` (panel focus) | `vestra.playlist/playlist.sort-title` |
+| By File Name (not in the menu) | `Ctrl+4` (panel focus) | `vestra.playlist/playlist.sort-filename` |
+| By Extension (not in the menu) | `Ctrl+5` (panel focus) | `vestra.playlist/playlist.sort-extension` |
+| By Size (not in the menu) | `Ctrl+6` (panel focus) | `vestra.playlist/playlist.sort-size` |
+| By Duration (not in the menu) | `Ctrl+7` (panel focus) | `vestra.playlist/playlist.sort-duration` |
+| By Date (not in the menu) | `Ctrl+8` (panel focus) | `vestra.playlist/playlist.sort-date` |
+| Random Order (not in the menu) | `Ctrl+9` (panel focus) | `vestra.playlist/playlist.sort-shuffle` |
+| By Folder (not in the menu) | `Ctrl+0` (panel focus) | `vestra.playlist/playlist.sort-folder` |
+| Sort by Path (not in the menu) |  | `vestra.playlist/playlist.sort-path` |
+| Reverse Current Order (not in the menu) |  | `vestra.playlist/playlist.sort-reverse` |
+| Select All (not in the menu) | `Ctrl+A` (panel focus) | `vestra.playlist/playlist.select-all` |
+| Search (not in the menu) | `Ctrl+S` (panel focus) | `vestra.playlist/playlist.search` |
+| Open List File… (not in the menu) | `F3` (panel focus) | `vestra.playlist/playlist.list-open-list` |
+| Save List… (not in the menu) | `F2` (panel focus) | `vestra.playlist/playlist.list-save-list` |
+| Close List (not in the menu) | `F6` (panel focus) | `vestra.playlist/playlist.close` |
+| Playlist Settings… (not in the menu) | `F5` (panel focus) | `vestra.playlist/playlist.settings` |
+
+#### Binding syntax
+
+```text
+binding  = { modifier "+" } input      modifiers in the order Ctrl, Alt, Shift, Cmd, each at most once
+input    = key name | one printable symbol | mouse input
+```
+
+- A letter is its key name in capitals, whatever the case typed: `Shift+E`.
+- A symbol is written as typed and never with `Shift`: `">"`, not `"Shift+."`; `"!"`, not `"Shift+1"`. The `+` key is always `Plus`, also with modifiers (`Alt+Plus`).
+- `"5"` is the main keyboard's 5 only, `"Numpad5"` the keypad's only; `"Enter"` is not the keypad's Enter (`"NumpadEnter"`). The menu shows keypad names as `Num5`, `Num+`, `NumEnter`.
+- `Delete` is the forward-delete key ⌦ (fn+⌫ on a Mac laptop), `Backspace` is ⌫.
+- On macOS `Ctrl` also matches ⌘ and `Cmd` only ⌘; on Windows `Cmd` is the Windows logo key. Write `Ctrl+…` for a binding that works on both.
+- Mouse inputs apply over the video area only. The right button is not bindable (it opens the context menu).
+- Anything else fails with code `invalid` when the command is added.
 
-### Which calls keep only the newest value
+A menu item shows the first of its keyboard bindings that is in effect.
 
-| Latest value wins (safe on every move)                                                                                 | One request per call (do not call on every move)                                                                                                      |
-| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| VideoFilter VideoFilter`.set`, AudioFilter AudioFilter`.set` | Player.seek player.seek: use Player.scrub player.scrub() and `Scrub.seek` for a seek slider |
-| Player.setOutput player.setOutput (volume, mute)                                          | `player.setRate` and other player controls                                                                                                            |
-| `Scrub.seek` (about one seek per display frame)                                                                        | Osd.show osd.show: show a message on release                                                                             |
-| View properties (`bind`, `set`), OsdPanel.set OsdPanel.set                                | `JsonStore.save` is debounced (300 ms), so it is fine; anything you write yourself is not                                                             |
+#### Binding names
 
-### When the slow part is your own code
+| Field of `BINDING_INPUTS` | Names | Notes |
+| --- | --- | --- |
+| `modifiers` | `Ctrl`, `Alt`, `Shift`, `Cmd` | Modifiers, in the order a binding writes them. `Cmd` is ⌘ on macOS and the Windows logo key on Windows; on macOS `Ctrl` also matches ⌘. |
+| `letters` | `A`–`Z` | Letter keys, by key name whatever the case: `A` to `Z`. |
+| `digits` | `0`–`9` | Digit keys of the main keyboard: `0` to `9`. |
+| `functionKeys` | `F1`–`F24` | Function keys: `F1` to `F24`. |
+| `named` | `Space`, `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `Insert`, `Home`, `End`, `PageUp`, `PageDown`, `ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown`, `Plus`, `Numpad0`, `Numpad1`, `Numpad2`, `Numpad3`, `Numpad4`, `Numpad5`, `Numpad6`, `Numpad7`, `Numpad8`, `Numpad9`, `NumpadPlus`, `NumpadMinus`, `NumpadMultiply`, `NumpadDivide`, `NumpadEnter`, `NumpadDecimal` | 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. |
+| `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` | Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a double click. |
 
-If a move triggers your own asynchronous work (rendering a preview with `plugin.tools.run`, a network request), do not `await` it per callback: the SDK starts every callback without waiting for the previous one, so slow runs overlap and can finish out of order, leaving an _older_ result on screen. Give that work latest-value semantics yourself:
+#### Core actions
 
-```ts
-import type { Plugin } from "@vestra-player/sdk";
+The player's own playback commands, which plugin.host.run runs by id (capability `commands`). Their bindings are stored as `host/<action>`; what each one does is on HostAction.
 
-/** Run `work` for the newest value only: one run at a time; values that arrive meanwhile replace each other. */
-export function latest<T>(work: (value: T) => Promise<void>) {
-  let running = false;
-  let next: { value: T } | undefined;
-  return async (value: T) => {
-    next = { value };
-    if (running) return; // the running loop picks it up
-    running = true;
-    try {
-      while (next) {
-        const current = next.value;
-        next = undefined;
-        await work(current);
-      }
-    } finally {
-      running = false;
-    }
-  };
-}
+| Action | Menu item | Default bindings |
+| --- | --- | --- |
+| `stop` | Close | `F4` |
+| `play-pause` | Playback ▸ Play/Pause | `Space` |
+| `previous` | Playback ▸ Previous | `PageUp`, `Mouse:X1` |
+| `next` | Playback ▸ Next | `PageDown`, `Mouse:X2` |
+| `frame-back` | Playback ▸ Seek ▸ Previous Frame | `D` |
+| `frame-forward` | Playback ▸ Seek ▸ Next Frame | `F` |
+| `seek-backward` | Playback ▸ Seek ▸ Back 5 s | `ArrowLeft` |
+| `seek-forward` | Playback ▸ Seek ▸ Forward 5 s | `ArrowRight` |
+| `rate-normal` | Playback ▸ Speed ▸ Normal | `Z` |
+| `rate-down` | Playback ▸ Speed ▸ Slower 0.1 | `X` |
+| `rate-up` | Playback ▸ Speed ▸ Faster 0.1 | `C` |
+| `volume-up` | Audio ▸ Volume + | `ArrowUp`, `Mouse:WheelUp` |
+| `volume-down` | Audio ▸ Volume − | `ArrowDown`, `Mouse:WheelDown` |
+| `mute` | Audio ▸ Mute | `M` |
+
+The player also owns **Toggle Fullscreen** (`host/fullscreen`), **Leave Fullscreen** (`host/exit-fullscreen`, `Escape`, only in fullscreen) and **Quit** (`host/quit`); their keys are in Built-in commands.
+
+#### Keys the system takes first
+
+These keys may never reach a binding, because the system or the player takes them first; do not use them as defaults. This table is the one list of them; other pages link here.
+
+| Keys | Taken by |
+| --- | --- |
+| ⌃F1–⌃F8 (macOS) | The system's keyboard navigation (⌃F1 turns keyboard access on and off). A `Ctrl+F1` binding still fires with ⌘F1. |
+| ⌃← ⌃→ ⌃↑ ⌃↓ (macOS) | Spaces, Mission Control and application windows. The ⌘ versions of a `Ctrl+arrow` binding work. |
+| ⌘H, ⌘M (macOS) | The system: hide and minimize the application. A `Ctrl+H` or `Ctrl+M` binding then fires only with ⌃. |
+| ⌘Tab, ⌘Space (macOS) | The application switcher and Spotlight. |
+| F11, and F1–F12 on Apple keyboards (macOS) | F11 shows the desktop; on Apple keyboards the function keys are media keys unless fn is held. |
+| Ctrl+Alt+arrow keys (Windows) | Some graphics drivers, to rotate the screen. |
+| Most `Cmd+…` combinations (Windows) | The system, for the Windows logo key. `Cmd+Q` (**Quit**) does nothing there; the window's close button and Alt+F4 quit. |
+| **Standard close keys**: ⌘W (macOS); Ctrl+W, Ctrl+F4 (Windows) | The player, in a tool window, the floating sidebar and the Options window: they close that window exactly like the title-bar button (a tool window's `onClose` runs), even while a text field has focus, so neither Slint handlers nor bindings see them. In the main window they do nothing, so a binding for them fires there as usual. |
+| Right button, left drag on the video | The player: the context menu; moving the window in window mode. |
 
-declare function renderPreview(strength: number): Promise<string>; // your own slow work
+The defaults of the built-in commands are taken as well: a plugin default on the same input in the same scope loses to the player's own command and to plugins loaded earlier.
 
-export default async function activate(plugin: Plugin) {
-  let preview = "";
-  const window = plugin.windows.create("ui/preview.slint");
-  window.bind(() => ({ preview }));
-  const refresh = latest(async (strength: number) => {
-    preview = await renderPreview(strength);
-    plugin.update(); // changed after an await: send it now
-  });
-  window.on("strengthChanged", (strength: number) => refresh(strength));
-}
+## Reference: Platforms
+
+A plugin uses the same API on macOS and Windows; the player does the system-specific part. This table lists everything that behaves differently. A call that a system cannot serve fails with `unsupported`, so a plugin handles that code instead of testing for the system (plugin.app.system() tells the system when a plugin must know).
+
+| Feature | macOS | Windows |
+| --- | --- | --- |
+| Clipboard | Text; PNG and JPEG images as their original bytes. | Text; images are converted to a bitmap and PNG. |
+| Power.preventSleep | `caffeinate`. | The thread execution state. |
+| Dialogs.confirm | An `NSAlert` sheet on the active player window (usually the tool window that asked), with the custom buttons and the checkbox. | A task dialog owned by the active player window, titled "Vestra Player", with the custom buttons; `destructive` shows a warning icon; a `checkbox` is asked as a second yes/no dialog after the user confirms. |
+| MainWindow.setAlwaysOnTop | The floating window level. | Topmost window. |
+| MainWindow.setVideoArea | The visible screen area, without the menu bar and the Dock. | The whole display. |
+| MainWindow.setPictureInPicture | The system's picture-in-picture (macOS 14 or newer). | `unsupported`. |
+| DropModifiers | The pointer and ⌥ ⇧ ⌘ (`cmd` is ⌘). | The pointer and Alt, Shift, Ctrl (`cmd` is Ctrl). |
+| plugin.system (open, reveal) | Opened by the system; revealing several files selects all of them in one Finder window. | Opened by the shell; one Explorer window per folder. |
+| plugin.secrets | The login keychain. | The Credential Manager. |
+| App.system() | Version, build, model and displays. | Version, build, model and displays. |
+| Snapshots and exports (MediaCapture) | Available. | Available; needs FFmpeg 6.1 or newer. |
+| Generated streams (Player.openStream) | A Unix socket. | Loopback TCP with a token. |
+| Rendering | On the GPU (OpenGL), with hardware decoding. | In software, with hardware decoding copied back (`d3d11va-copy` and similar). |
+| Render options (RenderOptions) | Available; `peakDetect` has no effect. | `unsupported` (software rendering). |
+| Bindings | `Ctrl` also matches ⌘; `Cmd` is ⌘. | `Cmd` is the Windows logo key; `Cmd+Q` does not quit. |
+| Keys taken first, standard close keys | See Keys the system takes first. | See Keys the system takes first. |
+| Interface font | The system font; CJK falls back per character to the system's fonts (PingFang, Hiragino). | The system font; CJK falls back per character to Windows' CJK fonts in the interface language's order, then the bundled Noto Sans CJK SC (the chain). |
+| `Theme.font-mono` | Menlo | Consolas |
+
+Other systems have no released player; there, every feature in this table that needs the system fails with `unsupported` (always on top and `setVideoArea` with `unavailable`, `preventSleep` has no effect), and keys behave as on Windows.
+
+When the player runs without a user interface (headless, as in some automated setups), opening windows, mounting panels, dialogs, the OSD and `settings.show` fail with `unavailable` on every system.
+
+## Reference: Theme
+
+What a plugin's Slint file can import from the player's library. How Slint and TypeScript talk is in Windows, panels, settings pages, dialogs and the OSD; which token to use where is in Guidelines: interface.
+
+```slint nocheck
+import { Theme } from "@vestra/theme.slint";
+import { Icon } from "@vestra/icons.slint";
+import { Button, Slider, ToolTipArea, UrlInputRow } from "@vestra/widgets.slint";
+import { MarkdownView, MarkdownBlocks, MarkdownBlock } from "@vestra/markdown.slint";
 ```
 
-`plugin.update()` matters here. The SDK re-evaluates bound properties after a callback returns and again when its promise settles; a value you change **after an `await`** inside a longer task is otherwise shown only when that task ends. Call `plugin.update()` whenever such a task has something new to show.
+> **Current values; they may change — use the tokens.** The values below are what the player uses today. A later player may adjust them; a token keeps its meaning, a value you copy does not follow.
 
-## How-to: Remember a window's state between runs
+#### Colours
 
-**Goal:** a tool window comes back the way the user left it: its controls hold the last values, and if it was open when the player quit, it opens again at the next start.
+`Theme` colours follow the user's palette: `vestra`, the dark default, and `vestra-light` (player 0.4.0), whose video area stays dark. The player sets the palette on every view and again when the user switches, so read colours from `Theme` (they are read-only `out` properties) and never write a colour value yourself. The table shows both palettes' current values; the same values are THEME_PALETTES, for tests.
 
-A tool window keeps nothing by itself: closing it destroys the window instance, and the plugin process ends with the player. Keep the state in your plugin, store it with plugin.storage.json, show it with `bind`, and reopen the window during activation.
+| Token | Value in `vestra` | Value in `vestra-light` | Note |
+| --- | --- | --- | --- |
+| `Theme.bg-bar` | `#16141c` | `#f7f6fa` |  |
+| `Theme.bg-video` | `#0a090e` | `#0e0d12` |  |
+| `Theme.bg-list` | `#1a1821` | `#ffffff` |  |
+| `Theme.bg-panel` | `#201d28` | `#f1eff5` |  |
+| `Theme.line` | `#2b2734` | `#dcd8e4` |  |
+| `Theme.hover-bg` | `#28232f` | `#e9e6f0` |  |
+| `Theme.press-bg` | `#110f16` | `#dcd8e6` |  |
+| `Theme.selected-bg` | `#2f2840` | `#efe4fb` |  |
+| `Theme.text` | `#f5f3fa` | `#1c1924` |  |
+| `Theme.text-dim` | `#8e88a0` | `#6f6a7f` |  |
+| `Theme.text-list` | `#bdb8cb` | `#3b3748` |  |
+| `Theme.text-played` | `#6e6980` | `#9a95a8` |  |
+| `Theme.accent` | `#f72aa6` | `#d4128a` |  |
+| `Theme.accent-press` | `#c41a83` | `#a80d6c` |  |
+| `Theme.accent-disabled` | `#5a1d48` | `#ecbcd9` |  |
+| `Theme.icon-disabled` | `#3b3646` | `#c9c5d2` |  |
+| `Theme.playing` | `#2bb6ff` | `#0773ba` |  |
+| `Theme.button-bg` | `#2f2a3b` | `#e6e3ec` |  |
+| `Theme.button-hover` | `#3a3448` | `#dcd8e4` |  |
+| `Theme.button-press` | `#25202e` | `#cfcadb` |  |
+| `Theme.button-disabled` | `#1b1922` | `#efedf3` |  |
+| `Theme.danger` | `#ff5a5f` | `#c42b2b` | Errors and destructive actions: a failed status line, a Delete button. |
+| `Theme.accent-fill` | gradient 90°: `#fcc402 0%`, `#fb5a35 20%`, `#fa0aa8 45%`, `#7a0afa 72%`, `#10a8fc 100%` | gradient 90°: `#f5a700 0%`, `#f0442f 20%`, `#e0089a 45%`, `#6a08e8 72%`, `#0a95e6 100%` | Brand gradient for "progress" fills (seek bar, volume, sliders, accents). |
+
+`std-widgets.slint` controls (`CheckBox`, `ComboBox`, `LineEdit`…) are compiled in Slint's `fluent-dark` style and switched to their light colours in `vestra-light`; do not set `Palette.color-scheme` yourself.
+
+#### Sizes and fonts
+
+Corner radii, font sizes and control sizes are constants, the same in both palettes. `radius-control` rounds controls, menu rows and hover plates; `radius-panel` menus, panels and the OSD (4px and 8px since player 0.4.0; 3px and 6px before).
+
+| Token | Value | Note |
+| --- | --- | --- |
+| `Theme.radius-control` | `4px` |  |
+| `Theme.radius-panel` | `8px` |  |
+| `Theme.font-xs` | `9px` |  |
+| `Theme.font-body` | `11px` |  |
+| `Theme.font-tab` | `12px` |  |
+| `Theme.font-title` | `13px` |  |
+| `Theme.button-height` | `21px` |  |
+| `Theme.button-min-width` | `66px` |  |
+| `Theme.button-padding` | `8px` |  |
+| `Theme.button-primary-height` | `24px` |  |
+| `Theme.button-small-height` | `18px` |  |
+| `Theme.button-small-min-width` | `41px` |  |
+| `Theme.input-height` | `21px` |  |
+| `Theme.checkbox-row-height` | `18px` |  |
+| `Theme.label-height` | `14px` |  |
+| `Theme.form-row-gap` | `26px` |  |
+| `Theme.dialog-padding` | `14px` |  |
+
+- **No font family of its own.** Every window uses the system's interface font for Latin text; a plugin does not need to set a font, and a `default-font-family` it sets stays first. A character the font lacks falls back, character by character, to a font for its script.
+- **CJK fallback.** On macOS the system's own fallback (PingFang, Hiragino) covers Chinese, Japanese and Korean. On Windows the player sets a chain per script for every window, plugin windows included, and uses the first installed family that has the character:
+  1. Windows' CJK families in the interface language's order: for Han text, the language's own tradition first (Simplified Chinese, the default for other languages: Microsoft YaHei UI, Microsoft YaHei, DengXian, SimSun, NSimSun, SimHei; Traditional Chinese: Microsoft JhengHei UI, Microsoft JhengHei, PMingLiU, MingLiU; Japanese: Yu Gothic UI, Meiryo UI, Yu Gothic, Meiryo, MS UI Gothic, MS Gothic; Korean: Malgun Gothic, Gulim, Dotum, Batang), then the other traditions. Kana starts with the Japanese families, Hangul with the Korean, Bopomofo with the Traditional Chinese.
+  2. The family Windows' own fallback picks.
+  3. The bundled Noto Sans CJK SC, last, so CJK text never shows as boxes when an edition lacks the optional font packs.
+- **`Theme.font-mono`** is the system's monospace family: Menlo on macOS, Consolas on Windows (Platforms). CJK falls back in it too.
+
+#### Icons
+
+`@vestra/icons.slint` is the player's own icon set (player 0.4.0): round-capped, round-joined lines, 1.5px wide (1.25px for the small glyphs), never filled, each in its own box.
+
+```slint nocheck
+Icon { name: "play"; color: Theme.text; }                  // its box size
+Icon { name: "close"; width: 20px; height: 20px; }         // scaled
+```
+
+- The box is the icon's default size; set `width` and `height` to scale it. An unknown name draws nothing.
+- For a `Path` of your own, `Icons.commands(name)` returns the path data, `Icons.box-width(name)` and `Icons.box-height(name)` the box (the path's viewbox) and `Icons.line(name)` the line width.
+
+| Name | Box (px) | Line |
+| --- | --- | --- |
+| `play` | 12 × 14 | 1.5px |
+| `pause` | 12 × 14 | 1.5px |
+| `stop` | 12 × 12 | 1.5px |
+| `back` | 14 × 10 | 1.5px |
+| `forward` | 14 × 10 | 1.5px |
+| `open` | 14 × 12 | 1.5px |
+| `volume` | 13 × 10 | 1.5px |
+| `mute` | 13 × 10 | 1.5px |
+| `playlist` | 13 × 10 | 1.5px |
+| `detach` | 14 × 12 | 1.5px |
+| `attach` | 14 × 12 | 1.5px |
+| `close` | 14 × 13 | 1.5px |
+| `failed` | 10 × 10 | 1.25px |
+| `move-top` | 14 × 12 | 1.5px |
+| `move-up` | 14 × 12 | 1.5px |
+| `move-down` | 14 × 12 | 1.5px |
+| `move-bottom` | 14 × 12 | 1.5px |
+| `search` | 14 × 12 | 1.5px |
+| `chapter` | 12 × 12 | 1.25px |
+| `bookmark` | 12 × 12 | 1.25px |
+| `check-task` | 11 × 11 | 1.5px |
+| `check-box` | 9 × 9 | 1.5px |
+| `menu-check` | 14 × 14 | 1.5px |
+| `submenu` | 5 × 8 | 1.25px |
+| `scroll-up` | 8 × 5 | 1.25px |
+| `scroll-down` | 8 × 5 | 1.25px |
+| `caret-down` | 8 × 5 | 1.25px |
+| `sort-asc` | 7 × 4 | 1.1px |
+| `sort-desc` | 7 × 4 | 1.1px |
+| `tag-remove` | 7 × 7 | 1.25px |
+| `preview-play` | 8 × 9 | 1.25px |
+| `add` | 10 × 10 | 1.5px |
+| `remove` | 10 × 10 | 1.5px |
+| `sort` | 10 × 10 | 1.5px |
+
+#### Widgets
+
+`@vestra/widgets.slint`: compact controls drawn with the theme. Other controls come from `std-widgets.slint`.
+
+**`ToolTipArea`**: Hover for 600 ms to show `text` beside the pointer. The tip closes when the pointer leaves or presses; it shows again on the next hover.
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `text` | in `string` |  |  |
+| `showing` | out `bool` |  | The tip is showing (read-only). |
 
-### The complete example
+**`Button`**: Dialog button: text (21px, or 18px when `small`), or an icon button when `text` is empty and `icon` holds Path data drawn in an icon-width × icon-height viewbox (filled, or 1.5px round-capped lines when `stroked`, as the @vestra/icons.slint set). The caller sizes icon buttons.
 
-The **Brightness** window from Keep a slider responsive while dragging, now remembering the brightness and whether the window was open. The manifest is the same as there, without `ui.osd`:
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `text` | in `string` |  |  |
+| `icon` | in `string` |  |  |
+| `icon-width` | in `length` | `14px` |  |
+| `icon-height` | in `length` | `12px` |  |
+| `stroked` | in `bool` |  |  |
+| `enabled` | in `bool` | `true` |  |
+| `small` | in `bool` |  |  |
+| `checked` | in `bool` |  | Icon buttons: the "on" state, drawn in the accent colour. |
+| `clicked` | callback `()` |  |  |
+
+**`Slider`**: 2px line slider. Bar style (default): 8px round thumb, a white core in a 2px accent ring, gradient fill. Panel style (`panel: true`): 14×12 thumb, gradient fill. The track is `Theme.line` in both.
+
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `value` | in-out `float` |  |  |
+| `minimum` | in `float` | `0` |  |
+| `maximum` | in `float` | `1` |  |
+| `enabled` | in `bool` | `true` |  |
+| `panel` | in `bool` |  |  |
+| `changed` | callback `(float)` |  |  |
+| `released` | callback `(float)` |  |  |
 
-```json
-{
-  "id": "examples.brightness",
-  "version": "1.0.0",
-  "apiVersion": "vestra/1",
-  "entry": "main.ts",
-  "minPlayerVersion": "0.3.0",
-  "capabilities": [
-    "commands",
-    "ui.window",
-    "processing.video",
-    "playback.read",
-    "events"
-  ]
-}
-```
+**`UrlInputRow`**: Link input: a multi-line input and [Open] [Cancel]. Enter or the confirm button accepts (Shift+Enter starts a new line), Esc or Cancel cancels. No validation here: the plugin checks the address.
 
-`ui/brightness.slint` is unchanged: it declares `in-out property <float> brightness`, `in property <string> label` and the callbacks `brightness-changed(float)`, `brightness-released(float)` and `reset()` (the full file is on the slider page).
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `text` | in-out `string` |  |  |
+| `placeholder` | in `string` |  |  |
+| `confirm-text` | in `string` | `@tr("Open")` |  |
+| `cancel-text` | in `string` | `@tr("Cancel")` |  |
+| `enabled` | in `bool` | `true` |  |
+| `accepted` | callback `(string)` |  |  |
+| `cancelled` | callback `()` |  |  |
+| `focus-input` | function `()` |  |  |
+| `select-all` | function `()` |  |  |
 
-`main.ts`:
+A component's public functions are called from your own Slint code, through an element id: `row.focus-input()` puts the keyboard focus into `UrlInputRow`'s input (call it when the window opens, for example from `init`), `row.select-all()` selects its text.
 
-```ts
-import type { Plugin } from "@vestra-player/sdk";
+#### Markdown
 
-/** Everything the plugin remembers, in <dataDirectory>/brightness.json. */
-interface Saved {
-  /** −1–1, 0 = unchanged. */
-  brightness: number;
-  /** The window was open when the player quit. */
-  open: boolean;
-}
+`@vestra/markdown.slint` shows a document made by plugin.ui.markdown: give `blocks` its value. Links report `link-clicked(url)`, resolved against the document's base; the plugin decides what to open (usually plugin.system). `code-copy: true` adds a Copy button to code blocks that reports `copy-code(code)`; the plugin copies it (plugin.clipboard).
 
-const DEFAULTS: Saved = { brightness: 0, open: false };
+**`MarkdownBlocks`**: Markdown blocks without scrolling, as tall as their content.
 
-/** A missing, broken or outdated file falls back to DEFAULTS. */
-function isSaved(value: unknown): value is Saved {
-  const v = value as Partial<Saved> | null;
-  return (
-    typeof v === "object" &&
-    v !== null &&
-    typeof v.brightness === "number" &&
-    Math.abs(v.brightness) <= 1 &&
-    typeof v.open === "boolean"
-  );
-}
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `blocks` | in `[MarkdownBlock]` |  |  |
+| `code-copy` | in `bool` | `false` | A Copy button on code blocks, reporting `copy-code(code)`. |
+| `link-clicked` | callback `(string)` |  |  |
+| `copy-code` | callback `(string)` |  |  |
 
-export default async function activate(plugin: Plugin) {
-  // 1. Load: read once, synchronously; defaults if there is no valid file.
-  const store = plugin.storage.json<Saved>("brightness", {
-    defaults: DEFAULTS,
-    validate: isSaved,
-  });
-  /** Change part of the state; the file is written 300 ms after the last change. */
-  const remember = (patch: Partial<Saved>) =>
-    store.save({ ...store.value, ...patch });
+**`MarkdownView`**: A scrolling Markdown document.
 
-  const filter = plugin.video.filter("brightness");
-  const apply = () =>
-    filter.set([
-      {
-        kind: "eq",
-        brightness: store.value.brightness,
-        contrast: 1,
-        saturation: 1,
-        gamma: 1,
-      },
-    ]);
-  apply(); // the effect is back before the window is
+| Member | Kind | Default | Note |
+| --- | --- | --- | --- |
+| `blocks` | in `[MarkdownBlock]` |  |  |
+| `inset` | in `length` | `10px` | Space around the document. |
+| `code-copy` | in `bool` | `false` | A Copy button on code blocks, reporting `copy-code(code)`. |
+| `link-clicked` | callback `(string)` |  |  |
+| `copy-code` | callback `(string)` |  |  |
 
-  // 2. Show: the window always displays the stored state.
-  const window = plugin.windows.create("ui/brightness.slint");
-  window.bind(() => ({
-    brightness: store.value.brightness,
-    label: store.value.brightness.toFixed(2),
-  }));
-  window.on("brightnessChanged", (value: number) => {
-    remember({ brightness: Math.min(1, Math.max(-1, value)) });
-    apply();
-  });
-  window.on("reset", () => {
-    remember({ brightness: 0 });
-    apply();
-  });
+Struct **`MarkdownRow`**: One table row (cells are plain text).
 
-  // 3. Track whether it is open: only the user closing it counts as "closed".
-  window.onClose(() => remember({ open: false }));
-  const open = async () => {
-    await window.show();
-    remember({ open: true });
-  };
-  plugin.commands.add({
-    id: "brightness",
-    path: ["@video", "Brightness…"],
-    run: open,
-  });
+Struct **`MarkdownBlock`**: One displayed block. Plugins only pass these through; the fields are filled by the player.
 
-  // 4. Restore: reopen it if it was open when the player quit.
-  if (store.value.open) await open().catch(() => remember({ open: false }));
-}
+## Reference: Command line
+
+`vestra-plugin` comes with `@vestra-player/sdk` and works in any project that depends on it (`npx vestra-plugin …`, or an npm script). A plugin directory is a directory with `manifest.json`; the default is the current directory, and several can be given at once.
+
+```text
+usage: vestra-plugin <check|build|test|pack> [plugin-dir...] [--version x.y.z] [--out dir]
+       vestra-plugin i18n extract [plugin-dir...] [--locale <lang>]...
+       vestra-plugin i18n check [plugin-dir...]
 ```
 
-### How it works
+| Command | Does |
+| --- | --- |
+| `vestra-plugin check` | strict type check of the plugin's .ts files and tests/*.ts |
+| `vestra-plugin build` | check, then write dist/: .ts → .js with types stripped, other package files copied, dist/manifest.json with `version` |
+| `vestra-plugin test` | node --test on tests/*.test.{ts,mjs} |
+| `vestra-plugin pack` | build, then dist/ → <out>/<id>-<version>.vxp (a zip; default out: the current directory) with its sha256 and size |
+| `vestra-plugin i18n extract` | find the texts to translate (@tr in .slint files, the texts handed to commands.add, osd.show, dialogs, settings and panel titles, the manifest's display fields), write locales/messages.pot and merge it into every locales/<lang>.po (translations kept, vanished ones marked obsolete); --locale <lang> starts a new language |
+| `vestra-plugin i18n check` | coverage per language, placeholder and plural problems, a stale messages.pot, and texts that cannot be translated (composed in TypeScript, not literals, not English, Slint text without @tr) as warnings; fails (exit 1) on a stale messages.pot, a .po missing messages, an unreadable file |
 
-- **Load once, at activation.** `storage.json` reads `<dataDirectory>/brightness.json` synchronously when it is created. A file that cannot be parsed or fails `validate` is renamed to `brightness.json.bad-<timestamp>` and `defaults` is used, so a damaged or older file never breaks the plugin. Always pass a `validate` function: the file is outside your control.
-- **Bind the stored value, not a copy.** `window.bind` reads `store.value` in every update pass, so whatever changes the state (a callback, Reset, a command) updates the window, and a window opened later starts with the current values.
-- **Save on every change; the store debounces.** `save()` replaces `store.value` at once and writes the file 300 ms after the last call (a temporary file, then a rename). Dragging the slider writes the file once, after the drag. When the plugin stops (the player quits, the user disables the plugin), the store is flushed, so the last value is not lost.
-- **"Open" means "the user did not close it".** `onClose` runs only when the user closes the window (title-bar button, ⌘W, Ctrl+W, Ctrl+F4). When the player quits, the plugin stops and its windows close _without_ `onClose`, so `open` stays `true` and the window comes back next time. That is the behaviour users expect from an application's tool windows.
-- **Restore after binding.** The window is created and bound before `open()` runs, so it opens with the stored values and without flashing defaults. If it cannot open (for example in a player without a user interface), the plugin forgets that it was open instead of failing activation.
+Exit codes: 0 on success, 1 when a command failed for any of the directories (each one is still tried), 2 for an unknown command.
 
-### What you cannot restore
+#### Rules every command applies
 
-- **Position and size.** The operating system places a tool window when it opens. The player does not remember tool window frames, and the API has no way to read or set them; the window's size comes from its Slint file (`width`, `preferred-width` and so on).
-- **State that only Slint knows.** Text in a field, a scroll position or a selected tab survives only if a callback reports it to the plugin and the plugin stores it and writes it back as a property, as `brightness` does here.
+- **The manifest first.** Every command checks `manifest.json` against the player's own rules (Manifest) before anything else. `check` also prints hints that do not fail, such as an id without the `<owner>.` prefix the official repository needs.
+- **Type checking** extends the nearest `tsconfig.json` at or above the plugin directory (up to the repository root), else built-in strict settings (`strict`, `NodeNext`, `verbatimModuleSyntax`, `erasableSyntaxOnly`). Only the plugin's own files and `tests/` are checked, with the SDK's own TypeScript 5.x.
+- **`import type` only.** A plugin never imports SDK code at run time; `build` fails when the output still refers to `@vestra-player/sdk`. Tests import `@vestra-player/sdk/testing` freely.
+- **Translations.** With a `locales/` folder, `check` prints the `i18n check` problems as warnings and `build` compiles each `locales/<lang>.po` to `dist/locales/<lang>.json` (Translate a plugin).
 
-### Variations
+#### What build puts into dist/
 
-- **Several windows from one file** (one per document, created with `windows.create(file, { id })`): store an object keyed by the window id and restore each one.
-- **Preferences rather than state:** a choice such as "reopen my windows at startup" belongs on a settings page (plugin.settings.page) that reads and writes the same store (the `SettingsPage` reference has an example).
-- **Large or binary data:** write your own files in plugin.dataDirectory (to a temporary name, then rename) and keep only small settings in `storage.json`.
+- `.ts` files with the types stripped and relative imports changed to `.js`; `dist/manifest.json` with `entry` changed to `.js` and `version` written.
+- `.slint` and `.mjs` files, data files and `licenses/` as they are; the manifest's `icon`, `readme` and `changelog`, and `README.md` and `CHANGELOG.md` when present.
+- Left out: `tests/`, `node_modules/`, `vendor/`, other `*.md`, `tsconfig*.json`, `package*.json`, `.po` and `.pot` files.
+- The version is `--version`, else the manifest's `version`, else `package.json`'s. `--version` takes one plugin directory.
+- `dist/` is build output; do not commit it.
+
+`pack` runs `build` and writes `dist/` as `<id>-<version>.vxp` (a zip) to `--out` (default: the current directory), printing its size and SHA-256. The same input gives the same bytes (sorted entries, fixed timestamps), so a package can be rebuilt and compared.
+
+#### The vestra field of package.json
+
+A plugin with npm dependencies says how to package them in its own `package.json`:
+
+```json
+{
+  "vestra": {
+    "bundle": { "external": ["some-native-module"] },
+    "assets": ["vendor"]
+  }
+}
+```
+
+- `"bundle": true` or `{ "external": [...] }` bundles the entry and its dependencies into one file with the plugin's own `esbuild` (a devDependency). **A plugin with runtime dependencies must bundle**: the package has no `node_modules`.
+- `"assets": [...]` copies extra files or directories into the package as they are.
+
+To try a plugin without packing it, start the player with `--plugin <folder>`; it runs `main.ts` directly.
 
 ## API: @vestra-player/sdk
 
@@ -1006,6 +3061,19 @@ change).
 | `host` | Any other failure inside the player; `message` is the player's reason. |
 | `disabled` | The plugin is being stopped; pending requests fail with it. |
 | `unknown`, `rejected`, `expired` | After a transport problem the SDK could not confirm the outcome (does not happen in normal operation). |
+| `activation` | The plugin opened a tool window while its activation was still pending and the player could not track it. |
+| `command` | The player could not run or update a command it no longer knows for this plugin (removed meanwhile, or another plugin's). |
+| `input-overflow` | `openStream` input: the player's queue of physical key transitions was full; the input was revoked and its keys released. |
+| `internal` | An internal step of the player failed (keeping an operation's result, a subtitle or media job); `message` has the reason. |
+| `javascript`, `slint` | Packages.validate: the package's entry module does not pass `node --check` / one of its Slint files does not compile; `message` has the diagnostics. |
+| `owner` | A resolver answered a request that belongs to another plugin's resolver. |
+| `pending` | An operation with the same token is still running in the player. The SDK waits and asks again, so it rarely reaches a plugin. |
+| `producer` | `openStream`: the player refused or lost the generated stream; `message` has the reason. |
+| `resolution` | A file or web resolver's result could not be opened; `message` has the reason. |
+| `revisionConflict` | Packages: the installed revision changed since it was read (another install, rollback or uninstall ran). Read again and retry; the SDK passes the revision it read, so this reaches plugins that act on old data. |
+| `source-geometry`, `source-geometry-unsupported` | The source's picture size or rotation could not be applied: invalid decoder dimensions / a rotation that is not a multiple of 90°. |
+| `source-unavailable` | The source is not ready (still loading, or its time or native binding is not available yet). |
+| `unknown-expired` | The player no longer knows the operation or snapshot (it expired or was released). The SDK maps it to `unknownExpired` results where it can; do not resubmit the operation blindly. |
 
 Errors thrown by handlers the SDK invokes go to Scope.onError. A
 rejected promise you forgot to `await` is only logged; it never crashes
@@ -1174,16 +3242,19 @@ 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.
+   * 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.
    *
-   * 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 Scope.storage.
+   * The path's format is not part of the API: do not derive another
+   * plugin's directory from it (a plugin manager reads
+   * PluginInfo.dataDirectory). Write files atomically (to a
+   * temporary name, then rename); for JSON settings prefer
+   * Scope.storage. Throws `unavailable` when the player provided
+   * none. See How a plugin runs.
    */
   readonly dataDirectory: string;
 }
@@ -1245,9 +3316,10 @@ Playback 200, Subtitles 300, Video 400, Audio 500, Screen 710, Settings
 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),
+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).
@@ -1311,8 +3383,8 @@ 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.
    *
    * Conflicts are not errors: the user's overrides win, then the player's
    * own commands, then the plugin loaded first; a shadowed binding takes
@@ -1605,8 +3677,10 @@ interface SlotState {
    * - `fullscreen`: the sidebar's fullscreen overlay is collapsed and pops
    *   out when the pointer reaches the right edge; treat it as "on" for a
    *   toggle button;
-   * - `idle`: the bottom bar in fullscreen, hidden after 3 seconds without
-   *   activity.
+   * - `idle`: the bottom bar in fullscreen while the pointer is outside the
+   *   bar's own band at the bottom of the screen (player 0.5.1: keys and
+   *   pointer motion elsewhere do not bring it back; before 0.5.1 it hid after
+   *   3 seconds without activity).
    */
   reason: "userHidden" | "space" | "fullscreen" | "idle" | null;
   /** The sidebar floats in its own window; always `false` for the bottom bar. */
@@ -2874,10 +4948,15 @@ interface PlaybackStats {
   backend: string;
   /** The playback session number. */
   session: number;
-  /** Frames the host has shown. */
+  /** Frames the video renderer produced. Not all of them reach the screen: a busy window shows only the newest one, so compare presentedFps. */
   framesShown: number;
-  /** Frames dropped, `null` when unknown. */
+  /** Frames dropped by the backend (mpv), `null` when unknown. */
   framesDropped: number | null;
+  /**
+   * New video frames the player window showed per second over the last second, measured by the player itself: draws of the main window that put a new picture on screen. Lower than `video.fps` when frames are lost after decoding and rendering (the window could not keep up with the source, or the display refreshes slower); `0` while paused. `null` when the player cannot measure it (no window, the first second, players before 0.5.1).
+   * @player 0.5.1
+   */
+  presentedFps: number | null;
   /** Every field is the backend's own value, `null` when it has none. */
   video: {
     /** Codec name. */
@@ -2902,8 +4981,10 @@ interface PlaybackStats {
     displayFps: number | null;
     /** Bits per second, updated per keyframe. */
     bitrate: number | null;
-    /** Hardware decoder in use, e.g. "videotoolbox"; "no" = software decoding. */
+    /** Hardware decoder in use, e.g. "videotoolbox", "d3d11va-copy"; "no" = software decoding. */
     hwdec: string | null;
+    /** How the video is decoded, from `hwdec`: `"hardware"` (the method is in `hwdec`) or `"software"`; `null` before a decoder runs. */
+    decoding: "hardware" | "software" | null;
     /** Transfer characteristic as mpv names it, e.g. "bt.1886", "pq", "hlg". */
     transfer: string | null;
   } | null;
@@ -4399,7 +6480,9 @@ type SubtitleStyle = {
   outline: number;
   /** Bottom margin 2–15 % of the video height. */
   marginPercent: number;
-  /** Timing offset −600000–600000 ms. */
+  /**
+   * Timing offset in milliseconds, −600000…600000 (±10 minutes); positive shows the subtitles later. Outside the range the player refuses the style with `invalid`.
+   */
   offsetMs: number;
   /** Bold text; default false. */
   bold?: boolean;
@@ -5396,6 +7479,61 @@ function startPlugin(activate: (plugin: Plugin) => unknown, options?: {
 }>;
 ```
 
+### CapabilityInfo
+
+What one manifest capability is for: the members it opens, the
+capabilities they also need, and how the plugin store describes it. An
+entry of CAPABILITY_INFO.
+
+```ts
+interface CapabilityInfo {
+  /**
+   * The members this capability opens, as `Interface.member` (for example `Commands.add` is `plugin.commands.add`). A call to one of them without the capability fails with code `capability`; `Plugin.video.filter` is `plugin.video.filter`. A member can be listed under more than one capability when it needs all of them (`Panel.onChange` needs `ui.mount` and `events`).
+   */
+  readonly apis: readonly string[];
+  /**
+   * Capabilities every member in CapabilityInfo.apis also needs: declare them as well. What only one member or one option needs (`Plugin.video.filter` also needs `events`) is documented at that member.
+   */
+  readonly requires: readonly string[];
+  /**
+   * How the plugin store and the player's install confirmation describe the capability to the user, in English (the player translates it). Two capabilities can share one description (`media.read` and `media.control`); the store then shows it once.
+   */
+  readonly label: string;
+  /**
+   * `true` when the store highlights the capability as one to think about before installing (it reaches outside the plugin's own features: the clipboard, every shortcut, the keychain, other plugins).
+   */
+  readonly risky: boolean;
+}
+```
+
+### CAPABILITY_INFO
+
+Every manifest capability the player knows (`vestra/1`), in the player's
+order, with the members it opens, the capabilities they also need and the
+store's wording. The player's tests check that the names agree with the
+player's `host/src/plugins.rs` and the labels with its plugin store.
+
+A member not listed under any capability needs none (`plugin.tools`,
+`plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui`,
+`plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
+and `plugin.packages.list`).
+
+```ts
+const CAPABILITY_INFO: Readonly<Record<string, CapabilityInfo>>;
+```
+
+### MESSAGE_LIMIT
+
+The longest message a plugin may send the player, in UTF-8 bytes of one
+protocol line with its newline (1 MiB). The player stops a plugin that
+writes a longer one, so the plugin's side refuses such a request before
+sending it: it rejects with code `limit`. Property values meet
+UI_VALUE_LIMITS before this.
+
+```ts
+const MESSAGE_LIMIT: number;
+```
+
 ### COMMAND_LIMITS
 
 The player's command registry caps, the same values as the player's own
@@ -5431,6 +7569,76 @@ agrees with the player's.
 const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings"];
 ```
 
+### BuiltinSubmenu
+
+A submenu that one of the player's built-in plugins declares: an entry of
+BUILTIN_SUBMENUS.
+
+```ts
+interface BuiltinSubmenu {
+  /**
+   * The submenu's key path: the English texts paths merge by, the built-in menu first by its key (`"Playback"` for `@playback`). Write these segments, followed by your command's title, to put a command into this submenu.
+   */
+  readonly path: readonly string[];
+  /** The built-in plugins that declare it (`vestra.history`). */
+  readonly plugins: readonly string[];
+}
+```
+
+### BUILTIN_SUBMENUS
+
+The submenus the player's built-in plugins declare, by key path, in menu
+order (built-in menus as in MENU_IDS, then top-level submenus).
+Menu paths merge by their English key, so a command whose path starts
+with the same keys appears in the same submenu, whatever the interface
+language; the submenu's title is the declaring plugin's translation. The
+player's own submenus (`Playback ▸ Speed`, `Playback ▸ Seek`) are not
+listed. The player's tests check that this list agrees with what its
+built-in plugins declare.
+
+```ts
+const BUILTIN_SUBMENUS: readonly BuiltinSubmenu[];
+```
+
+### BuiltinCommand
+
+A command the player or one of its built-in plugins registers: an entry
+of BUILTIN_COMMANDS.
+
+```ts
+interface BuiltinCommand {
+  /** `"host"` for the player's own commands, else the built-in plugin's id. */
+  readonly owner: string;
+  /** The command's id within its owner (`"play-pause"`, `"capture.save"`). */
+  readonly id: string;
+  /**
+   * The menu path by key (the English texts paths merge by), the leaf included; a built-in menu by its key (`"Video"`, not `"@video"`). Empty for a command that is not in the main menu (a panel shortcut).
+   */
+  readonly path: readonly string[];
+  /** The English title (the last segment of `path` when there is one). */
+  readonly title: string;
+  /** The default bindings, canonical, in the order the command declares them. */
+  readonly bindings: readonly string[];
+  /** `"panel"`: the bindings apply only while the owner's panel has focus. */
+  readonly focus: "panel" | null;
+}
+```
+
+### BUILTIN_COMMANDS
+
+The commands the player and its built-in plugins register when the
+player starts with nothing open, in menu order (commands outside the main
+menu last): their key paths, default bindings and owners. Use it to pick
+a menu place and default keys that do not collide with the player's (the
+user's own changes come on top; see Bindings). Menu items built
+from content (tracks, recent files, output devices) are not listed; their
+placeholders (`No Audio Tracks`) are. The player's tests check that this
+list agrees with what the player and its built-in plugins register.
+
+```ts
+const BUILTIN_COMMANDS: readonly BuiltinCommand[];
+```
+
 ### LOCALES
 
 The player's interface languages: English (the source language) first,
@@ -5472,6 +7680,95 @@ const TEXT_LIMITS: {
 };
 ```
 
+### THEME_PALETTES
+
+The colours of the player's palettes, by `Theme` colour token (without the
+`Theme.` prefix): `vestra`, the dark default, and `vestra-light` (player
+0.4.0). The player sets one of them on every view; a plugin reads the
+colours through `Theme` in its Slint files and never needs these values.
+They are here for the documentation (Reference: theme) and for tests that
+check a design against both palettes.
+
+Current values: a later player may adjust them, a token keeps its
+meaning. The `vestra` values are also the defaults of the SDK's copy of
+the palette (`slint/palette.slint`); the player's tests check both
+palettes against its own.
+
+```ts
+const THEME_PALETTES: Readonly<Record<"vestra" | "vestra-light", Readonly<Record<string, string>>>>;
+```
+
+### BINDING_INPUTS
+
+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.
+
+```ts
+const BINDING_INPUTS: Readonly<{
+  /** Modifiers, in the order a binding writes them. `Cmd` is ⌘ on macOS and the Windows logo key on Windows; on macOS `Ctrl` also matches ⌘. */
+  readonly modifiers: readonly ["Ctrl", "Alt", "Shift", "Cmd"];
+  /** Letter keys, by key name whatever the case: `A` to `Z`. */
+  readonly letters: readonly string[];
+  /** Digit keys of the main keyboard: `0` to `9`. */
+  readonly digits: readonly string[];
+  /** Function keys: `F1` to `F24`. */
+  readonly functionKeys: string[];
+  /**
+   * 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.
+   */
+  readonly named: readonly ["Space", "Enter", "Tab", "Escape", "Backspace", "Delete", "Insert", "Home", "End", "PageUp", "PageDown", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Plus", ...string[], "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. */
+  readonly mouse: readonly ["Mouse:LeftClick", "Mouse:LeftDoubleClick", "Mouse:LeftDoubleClick:LeftHalf", "Mouse:LeftDoubleClick:RightHalf", "Mouse:MiddleClick", "Mouse:X1", "Mouse:X2", "Mouse:WheelUp", "Mouse:WheelDown", "Mouse:WheelLeft", "Mouse:WheelRight"];
+}>;
+```
+
+### OSD_LIMITS
+
+The player's limits on the on-screen display (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.
+
+```ts
+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;
+}>;
+```
+
+### SECRET_LIMITS
+
+The player's limits on 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.
+
+```ts
+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;
+}>;
+```
+
 ### UI_VALUE_LIMITS
 
 The player's limits on one property value (a `PropValue` as written
@@ -5740,10 +8037,15 @@ interface PlaybackStats {
   backend: string;
   /** The playback session number. */
   session: number;
-  /** Frames the host has shown. */
+  /** Frames the video renderer produced. Not all of them reach the screen: a busy window shows only the newest one, so compare presentedFps. */
   framesShown: number;
-  /** Frames dropped, `null` when unknown. */
+  /** Frames dropped by the backend (mpv), `null` when unknown. */
   framesDropped: number | null;
+  /**
+   * New video frames the player window showed per second over the last second, measured by the player itself: draws of the main window that put a new picture on screen. Lower than `video.fps` when frames are lost after decoding and rendering (the window could not keep up with the source, or the display refreshes slower); `0` while paused. `null` when the player cannot measure it (no window, the first second, players before 0.5.1).
+   * @player 0.5.1
+   */
+  presentedFps: number | null;
   /** Every field is the backend's own value, `null` when it has none. */
   video: {
     /** Codec name. */
@@ -5768,8 +8070,10 @@ interface PlaybackStats {
     displayFps: number | null;
     /** Bits per second, updated per keyframe. */
     bitrate: number | null;
-    /** Hardware decoder in use, e.g. "videotoolbox"; "no" = software decoding. */
+    /** Hardware decoder in use, e.g. "videotoolbox", "d3d11va-copy"; "no" = software decoding. */
     hwdec: string | null;
+    /** How the video is decoded, from `hwdec`: `"hardware"` (the method is in `hwdec`) or `"software"`; `null` before a decoder runs. */
+    decoding: "hardware" | "software" | null;
     /** Transfer characteristic as mpv names it, e.g. "bt.1886", "pq", "hlg". */
     transfer: string | null;
   } | null;
@@ -6105,7 +8409,7 @@ The SDK is imported with `import type` only: the player passes the `plugin` obje
 
 (code: `main.ts`, part "command", below)
 
-- `path: ["@video", "Blur…"]` puts the item in the player's own **Video** menu. Menu paths are matched by their exact titles, and the player's menus are titled in its own language, so `["Video", "Blur…"]` would create a second top-level menu. A first segment that starts with `@` names a built-in menu whatever its title. The built-in menu stays where it is, and an item without `order` goes at the end of it.
+- `path: ["@video", "Blur…"]` puts the item in the player's own **Video** menu. Paths merge by their English keys in every interface language, so `["Video", "Blur…"]` reaches the same menu; the id form `@video` says plainly that a built-in menu is meant, and an unknown id fails with `invalid` instead of making a new menu (Menu paths). Players up to 0.4.2 titled their menus in Chinese and are reached only by the id. The built-in menu stays where it is, and an item without `order` goes at the end of it.
 - `run` opens the window, or shows it again after the user closed it. Returning the promise of `show()` lets the SDK report a failure to the plugin log.
 
 #### ui/blur.slint
@@ -6410,7 +8714,7 @@ When the plugin is disabled or the player quits, the SDK stops the stream the sa
 
 (code: `main.ts`, part "command", below)
 
-- `path: ["@open", "Signal generator"]` puts the item in the player's own **Open** menu. Menu paths are matched by their exact titles, and the player's menus are titled in its own language, so `["Open", …]` would add a second top-level menu. A first segment starting with `@` names a built-in menu whatever its title.
+- `path: ["@open", "Signal generator"]` puts the item in the player's own **Open** menu. Paths merge by their English keys in every interface language, so `["Open", …]` reaches the same menu; the id form `@open` names the built-in menu explicitly and also reaches it in players up to 0.4.2, whose menus were titled in Chinese (Menu paths).
 - `checked` is a function. The SDK calls it again after every handler and every `onStop`, and updates the check mark when the result changes.
 - `run` starts the stream when there is none and stops it when there is one. It returns the promise so that a failure reaches the plugin log.
 
@@ -7370,13 +9674,13 @@ A window that shows a formatted Markdown document with the player's `MarkdownVie
 
 - `commands` for the menu item, `ui.window` for the window. `plugin.ui.markdown` needs no capability.
 - `minPlayerVersion: "0.2.0"`: `ui.markdown` is new in that version, and older players refuse the plugin with a clear message.
-- `name` to `license` are display fields for the plugin manager. They do not affect how the plugin runs, and any plugin can have them; Getting started lists their rules.
+- `name` to `license` are display fields for the plugin manager. They do not affect how the plugin runs, and any plugin can have them; Manifest lists their rules.
 
 #### The package file
 
 (code: `package.json`, below)
 
-`vestra-plugin build` leaves Markdown files out of the package (except the README), so `sample.md` is listed under `"vestra": { "assets": [...] }`, which copies files into the package as they are. `assets/icon.png` needs no entry: the build copies images anyway.
+`vestra-plugin build` leaves Markdown files out of the package (except `README.md`, `CHANGELOG.md` and the manifest's `readme` and `changelog`; see What build puts into dist/), so `sample.md` is listed under `"vestra": { "assets": [...] }`, which copies files into the package as they are. `assets/icon.png` needs no entry: the build copies images anyway.
 
 #### The window
 
@@ -7416,7 +9720,8 @@ host.markdown() reads the document back from the window's property: its `text` a
 
 1. **Open links.** Add `callback open-link(string);` to the window, forward `link-clicked(url) => { root.open-link(url); }` from `MarkdownView`, and handle it with `window.on("openLink", (url: string) => plugin.system.openUrl(url))` before the first `show()`.
 2. **Remote images.** Put `![Avatar](https://github.com/vestrasys.png?size=128)` in the document: `ui.markdown` downloads `https:` images first (pass `remoteImages: false` to turn that off).
-3. **Show the plugin's own README** instead of `sample.md`; the build always packs the README.
+3. **Copy code.** Set `code-copy: true` on `MarkdownView`: code blocks get a **Copy** button (labelled in the interface language) that reports `copy-code(code)`. Forward it as a callback and copy the text with plugin.clipboard, which needs the `clipboard` capability.
+4. **Show the plugin's own README** instead of `sample.md`; the build always packs the README.
 
 #### examples/markdown/manifest.json