@vestra-player/sdk 1.5.13 → 1.5.14

package/llms.txt

@@ -1,22 +1,14 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.13: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
-
-**How plugins run**
-
-- Each plugin runs in its own Node.js process (Node.js 26, which the player ships) started by the player.
-- The player loads the entry module and calls its **default export** `activate(plugin)`.
-- 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.
-- Plugins are trusted code.
-- The API is the same on macOS and Windows.
+> @vestra-player/sdk 1.5.14: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
 
 **Rules**
 
-- **Only the public SDK.** Import `@vestra-player/sdk` with `import type` only (a runtime import fails `vestra-plugin build`) and `@vestra-player/sdk/testing` only in tests. `@vestra-player/sdk/runtime` and the SDK's internal modules are for the player.
-- **No other plugins.** Do not import another plugin's code, read its directory or data directory, or talk to it privately (shared files, sockets, messages). A plugin must load, run and stop while no other plugin is installed. Plugins share only what the API makes public: player state, timeline marks, menus, settings pages.
-- **No system commands.** Do not run `open`, `sips`, `plutil`, `security`, `cmd`, `powershell` or similar. Use the API (`plugin.system` to open files and links, `plugin.clipboard`, `plugin.secrets`, `plugin.tools` for ffmpeg and ffprobe) or portable Node.js code. If the API lacks something every system needs, ask for it in the SDK repository.
+- **Only the public SDK.** Import `@vestra-player/sdk` with `import type` only (a runtime import fails `vestra-plugin build`) and `@vestra-player/sdk/testing` only in tests.
+- **No other plugins.** Do not import another plugin's code, read its directory or data directory, or talk to it privately (shared files, sockets, messages).
+- **No system commands.** Do not run `open`, `sips`, `plutil`, `security`, `cmd`, `powershell` or similar.
 - **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.
+- **Your own id.** `<owner>.<name>`, where the owner is your GitHub user or organization.
 
 **Files**
 
@@ -29,7 +21,7 @@ my-plugin/
   package.json         dev dependency and scripts
 ```
 
-**manifest.json** (every field; unknown fields and capabilities are rejected; id ≤ 128 bytes, name, author ≤ 64 characters, punchline ≤ 120, description ≤ 2000, tags ≤ 8 of ≤ 24 characters, license ≤ 64, sourceUrl ≤ 2048 bytes, icon PNG or JPEG ≤ 512 KB and 1024 px per side, readme, changelog ≤ 256 KB)
+**manifest.json**
 
 ```json
 {
@@ -37,21 +29,12 @@ my-plugin/
   "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"
+  "capabilities": ["commands", "ui.osd", "playback.read", "events"]
 }
 ```
 
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2025–2087.
+
 **main.ts**
 
 ```ts
@@ -66,62 +49,45 @@ export default async function activate(plugin: Plugin) {
 }
 ```
 
-**Capabilities** (a call without its capability fails with `capability`)
-
-- `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`.
-
-**Test** (`tests/*.test.ts`, run by `vestra-plugin test`)
-
-```ts
-// tests/main.test.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("shows the position", async () => {
-  const { host, stop } = await startPlugin(activate, {
-    directory: new URL("..", import.meta.url), // reads manifest.json
-  });
-  host.setSource({ phase: "ready", position: 12, duration: 60 });
-  await host.settle();
-  await host.command("where").run();
-  assert.deepEqual(host.osd, ["12.0 s of 60.0 s"]);
-  await stop();
-});
-```
+**Capabilities** (a call without one fails with `capability`)
+
+- `producer.av`: Player.openStream (also `playback.control`)
+- `playback.read`: Player.state/refresh/stats/chapters/audioDevices, Timeline.marks
+- `playback.control`: Player.open/setPaused/seek/setRate/restart/close/scrub/setOutput/provideSequence/next/previous/addAudioTrack/selectAudioTrack/step/setStepSeek/setLoop/setAudioDevice, Power.preventSleep
+- `source.resolve`: Resolvers.add
+- `events`: Player/Subtitles/Timeline/MainWindow/Appearance/PanelSlot/Panel/BackdropSlot.onChange, Resolvers.onFileTypesChange
+- `commands`: Commands.add, Host.run
+- `ui.window`: Windows.create
+- `ui.mount`: Panels.mount/bottom/sidebar/backdrop, PanelSlot/Panel/BackdropSlot.onChange
+- `ui.dialog`: Dialogs.confirm/openFile/openFiles/openDirectory/saveFile
+- `plugins.manage`: Packages.validate/validateArchive/rollback/setEnabled/uninstall
+- `processing.video`: Plugin.video.filter/video.view/video.render (also `playback.read`)
+- `processing.audio`: Plugin.audio.filter (also `playback.read`, `events`)
+- `subtitles.read`: Subtitles.state/onChange/refresh
+- `subtitles.control`: Subtitles.select/load/remove/setStyle
+- `media.read`: MediaCapture.capture, Snapshot.export (also `media.control`)
+- `media.control`: MediaCapture.capture, Snapshot.export (also `media.read`)
+- `ui.osd`: Osd.show/panel
+- `clipboard`: Clipboard.readText/writeText/writeImage
+- `window.control`: MainWindow.setVideoArea/setAlwaysOnTop/setCursorAutoHide/setPictureInPicture
+- `bindings.manage`: Bindings.list/set/reset/onChange
+- `timeline.marks`: Timeline.layer
+- `ui.drop`: Drops.provide, Panel.onDrop
+- `ui.settings`: Settings.page/show
+- `ui.theme`: Appearance.set/setLanguage
+- `secrets`: Secrets.get/set/delete
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2088–2130.
+
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`; `host` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1587–1752; TestHost: L6649.
 
 **Command line**
 
-- `vestra-plugin check [dir...]`: Checks the manifest, then a strict type check of the plugin and its tests.
-- `vestra-plugin test [dir...]`: Runs `node --test` on `tests/*.test.{ts,mjs}`.
-- `vestra-plugin build [dir...] [--version x.y.z]`: Writes `dist/`: types stripped, files copied, manifest versioned.
-- `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]`: Builds, then packs `dist/` as `<id>-<version>.vxp`.
-- `vestra-plugin i18n extract [dir...] [--locale lang]`: Collects the texts to translate into `locales/`, keeping translations.
-- `vestra-plugin i18n check [dir...]`: Translation coverage and untranslatable text; fails on stale catalogs.
+- `vestra-plugin check`: strict type check of the plugin's .ts files and tests/*.ts
+- `vestra-plugin build`: check, then write dist/
+- `vestra-plugin test`: node --test on tests/*.test.{ts,mjs}
+- `vestra-plugin pack`: build, then dist/ → <out>/<id>-<version>.vxp
+- `vestra-plugin i18n extract`: find the texts to translate, write locales/messages.pot and merge it into every locales/<lang>.po
+- `vestra-plugin i18n check`: coverage per language, placeholder and plural problems, a stale messages.pot
 - `vestra-player --plugin <dir>` runs a plugin from source, no build needed.
 
 **Error codes** (`error.code`; branch on it, never on `message`)
@@ -131,79 +97,49 @@ test("shows the position", async () => {
 - `invalid`: A bad argument
 - `missing`: The target does not exist
 - `busy`: The player is still doing a previous call of the same kind
-- `conflict`: Another plugin owns the resource, or this plugin already uses the id
+- `conflict`: Another plugin owns the resource
 - `unavailable`: Not possible right now
 - `unsupported`: Not possible on this system, build or source
 - `failed`: The operation ran and failed
 - `aborted`: An `AbortSignal` fired
 - `timeout`: A time limit ran out
-- `limit`: A player-wide limit was reached, a property value is over the limits of PropValue, or a request is longer than the player's 1 MiB message
-- `reserved`: Packages.validate, PackageCandidate.install: the id is `vestra` or starts with `vestra.`, which only the player's built-in plugins use
+- `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
+- `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player or another `apiVersion`
-- `ui-prepare`: The player could not prepare a mounted panel or a settings page
-- `ui`: The player could not apply a property to a tool window or a settings page, or could not build the Options window
-- `disabled`: The plugin is being stopped
-- Others: PluginError, llms-full.txt L974.
+- Others: PluginError, llms-full.txt L3027.
 
 ## Reference
 
-- [Full reference](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt): in the package at node_modules/@vestra-player/sdk/llms-full.txt.
-- [Tutorial: Getting started](https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html): L9–280
-- [Concept: Windows, panels, settings pages, dialogs and the OSD](https://vestrasys.github.io/vestra-player-sdk/documents/Windows__panels__settings_pages__dialogs_and_the_OSD.html): L281–626
-- [How-to: Keep a slider responsive while dragging](https://vestrasys.github.io/vestra-player-sdk/documents/Keep_a_slider_responsive_while_dragging.html): L627–801
-- [How-to: Remember a window's state between runs](https://vestrasys.github.io/vestra-player-sdk/documents/Remember_a_window_s_state_between_runs.html): L802–931
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L932–4427
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4428–5538
+- [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; the pages are on the [site](https://vestrasys.github.io/vestra-player-sdk/).
+- Tutorials: Getting started L9–214
+- Concepts: How a plugin runs L215–364; Commands, menus and key bindings L365–462; Playback state, controls and sources L463–584; Video and audio processing L585–662; Windows, panels, settings pages, dialogs and the OSD L663–949
+- How-to: Keep a slider responsive while dragging L950–1124; Remember a window's state between runs L1125–1254; Translate a plugin L1255–1438; Migrate a plugin to English source text L1439–1586; Test a plugin L1587–1752; Publish a plugin L1753–1841
+- Guidelines: Interface guidelines L1842–1926; Menu guidelines L1927–2024
+- Reference: Manifest L2025–2087; Capabilities L2088–2130; Limits L2131–2225; Commands, menus and bindings L2226–2694; Platforms L2695–2723; Theme L2724–2928; Command line L2929–2984
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L2985–6484
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6485–7809
 
 ## API
 
-Where each module of `plugin` is declared:
-
-- Plugin L1153, Scope L1022, PluginError L974, Disposable L947
-- plugin.commands: Commands L1361
-- plugin.windows: Windows L1566
-- plugin.panels: Panels L2207
-- plugin.dialogs: Dialogs L2493
-- plugin.player: Player L2934
-- plugin.video: VideoFilter L3199, VideoView L3262, RenderOptions L3304
-- plugin.audio: AudioFilter L3223
-- plugin.subtitles: Subtitles L3402
-- plugin.media: MediaCapture L3562
-- plugin.resolvers: Resolvers L3667
-- plugin.packages: Packages L3907
-- plugin.osd: Osd L3135
-- plugin.host: Host L3083
-- plugin.clipboard: Clipboard L4024
-- plugin.power: Power L4044
-- plugin.tools: Tools L4077
-- plugin.storage: Storage L4120
-- plugin.system: System L4143
-- plugin.secrets: Secrets L4161
-- plugin.window: MainWindow L2330
-- plugin.app: App L2411
-- plugin.bindings: Bindings L3994
-- plugin.ui: Ui L1453
-- plugin.timeline: Timeline L2287
-- plugin.drops: Drops L1863
-- plugin.appearance: Appearance L1892
-- plugin.i18n: I18n L2034
-- plugin.settings: Settings L2140
+Where each module of `plugin` (`plugin.<module>`) is declared:
+
+- Plugin L3206, Scope L3075, PluginError L3027, Disposable L3000
+- Commands L3418; Windows L3623; Panels L4264; Dialogs L4550; Player L4991; video: VideoFilter L5256, VideoView L5319, RenderOptions L5361; audio: AudioFilter L5280; Subtitles L5459; media: MediaCapture L5619; Resolvers L5724; Packages L5964; Osd L5192; Host L5140; Clipboard L6081; Power L6101; Tools L6134; Storage L6177; System L6200; Secrets L6218; window: MainWindow L4387; App L4468; Bindings L6051; Ui L3510; Timeline L4344; Drops L3920; Appearance L3949; I18n L4091; Settings L4197.
 
 ## Examples
 
-Complete plugins with tests, in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples) and in llms-full.txt:
+Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L5955–6044
-- blur: A tool window with one slider that blurs the playing video. L6045–6306
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L6307–6639
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6640–6824
-- panel-menu: A sidebar panel with its own right-click menu. L6825–7030
-- menus: Radio menu items, separator groups and a menu item whose title changes. L7031–7190
-- theme-widgets: A tool window drawn with the player's theme and widgets. L7191–7354
-- markdown: A window that shows a Markdown document. L7355–7548
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L7549–7716
+- hello: The README Quick start: one menu command and an on-screen message. L8226–8315
+- blur: A tool window with one slider that blurs the playing video. L8316–8577
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8578–8910
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L8911–9095
+- panel-menu: A sidebar panel with its own right-click menu. L9096–9301
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9302–9461
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9462–9625
+- markdown: A window that shows a Markdown document. L9626–9820
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L9821–9988
 
 ## Optional
 
-- [Changelog](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md): changes per version and the player version each addition needs.
-- Declarations with every doc comment: node_modules/@vestra-player/sdk/dist/plugin/types.d.ts, dist/plugin/testing.d.ts; Slint widgets: slint/vestra/*.slint.
+- [Changelog](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md); full doc comments in dist/plugin/*.d.ts; Slint library in slint/vestra/.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.13",
+  "version": "1.5.14",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {
@@ -48,6 +48,7 @@
     "docs": "typedoc",
     "docs:check": "node scripts/check-docs.mjs",
     "docs:llms": "node scripts/llms.mjs",
+    "docs:tables": "node scripts/doc-tables.mjs",
     "examples": "node scripts/check-examples.mjs",
     "format": "prettier --write \"{src,test,bin,scripts,examples}/**/*.{ts,mjs}\" package.json tsconfig.json tsconfig.check.json typedoc.json .oxlintrc.json examples/tsconfig.json \"examples/*/package.json\"",
     "format:check": "prettier --check \"{src,test,bin,scripts,examples}/**/*.{ts,mjs}\" package.json tsconfig.json tsconfig.check.json typedoc.json .oxlintrc.json examples/tsconfig.json \"examples/*/package.json\"",