@vestra-player/sdk 1.5.25 → 1.5.26

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.25: full reference
+# @vestra-player/sdk 1.5.26: 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.
 
@@ -65,6 +65,29 @@ my-plugin/
 }
 ```
 
+Add a `tsconfig.json` for your editor. The `plugins` entry turns on the SDK's TypeScript plugin, which marks a call whose capability the manifest does not declare as you type (Capabilities):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "plugins": [{ "name": "@vestra-player/sdk/ts-plugin" }]
+  },
+  "include": ["*.ts", "tests/*.ts"]
+}
+```
+
+In VS Code, open a `.ts` file, run **TypeScript: Select TypeScript Version** and pick **Use Workspace Version** (the TypeScript the SDK installed): editors load a project's language-service plugins only with the project's own TypeScript.
+
 #### The manifest
 
 ```json
@@ -81,7 +104,7 @@ my-plugin/
 - `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"`.
+- `capabilities` lists what the plugin may do. A call to a member whose capability is missing fails with `code: "capability"`; the editor (with the `tsconfig.json` above) and `vestra-plugin check` point such calls out before the plugin runs.
 
 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.
 
@@ -2271,6 +2294,7 @@ A plugin lists what it may do in the manifest's `capabilities` (Manifest). A cal
 **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`.
+- The changes of Subtitles (`select`, `load`, `remove`, `setStyle`) also need `subtitles.read`: they read the current selection first.
 - 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.
@@ -2279,6 +2303,21 @@ A plugin lists what it may do in the manifest's `capabilities` (Manifest). A cal
 
 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).
 
+#### Catching a missing capability
+
+The player refuses a request whose capability the manifest does not declare, at run time. The SDK finds such calls earlier, with one rule: the player's own table of which request needs which capability (copied from the player), and the requests each member above sends. Nothing has to be remembered:
+
+| Where                                     | How                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The editor                                | An error at the member, "`Player.seek` needs the capability "playback.control", which manifest.json does not declare", with the quick fix **Add 'playback.control' to manifest.json**. It comes from the TypeScript plugin `@vestra-player/sdk/ts-plugin`, listed in the project's `tsconfig.json` (`"plugins": [{ "name": "@vestra-player/sdk/ts-plugin" }]`, as in Getting started). In VS Code, run **TypeScript: Select TypeScript Version** → **Use Workspace Version**: editors load a project's plugins only with the project's own TypeScript. `tsc` ignores language-service plugins. |
+| `vestra-plugin check`, `build` and `pack` | `check` reports each use as `file:line:column` with the member, the capability and the request, and fails; `build` and `pack` run `check` first, so a package cannot be made with a missing capability. `check --json` prints the findings as JSON (Command line).                                                                                                                                                                                                                                                                                                                                                      |
+
+The TypeScript plugin runs inside the editor's TypeScript server, on the editor's own Node.js, and needs that Node.js to be version 22.12 or later (the plugin is an ES module loaded with `require()`; the SDK itself needs 26, but the editor brings its own); current VS Code qualifies. With an older one the server logs that it could not load `@vestra-player/sdk/ts-plugin` and the editor shows no capability errors; `vestra-plugin check` still reports them. The quick fix edits the saved `manifest.json` (editors do not share unsaved JSON buffers with the TypeScript server) and keeps its layout and line endings.
+
+The manifest is the nearest `manifest.json` above the file. Only the plugin's own code is checked: `tests/` (tests choose their capabilities in `startPlugin`), `node_modules/`, `dist/` and `vendor/` are not. A member needs the capabilities its requests need and those capabilities' **Also needs**, so a `video.filter` without `playback.read` is reported too.
+
+The check follows types, not names: `plugin.player.seek`, `const { player } = plugin; player.seek(…)`, a function taking a `Player`, `plugin.clipboard["readText"]` and members of objects other members return (`panel.onChange` on a mounted panel) are all found. Not found: access with a computed name (`player[name]`), values typed `any`, plain JavaScript without types, and options that need more than the member (a `processed` capture, a file resolver). The player's check at run time stays: it is the boundary, since a plugin can bypass the SDK.
+
 ## 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`.
@@ -3095,13 +3134,14 @@ Struct **`MarkdownBlock`**: One displayed block. Plugins only pass these through
 
 ```text
 usage: vestra-plugin <check|build|test|pack> [plugin-dir...] [--version x.y.z] [--out dir]
+       vestra-plugin check [plugin-dir...] --json
        vestra-plugin i18n extract [plugin-dir...] [--locale <lang>]...
        vestra-plugin i18n check [plugin-dir...]
 ```
 
 | Command | Does |
 | --- | --- |
-| `vestra-plugin check` | strict type check of the plugin's .ts files and tests/*.ts |
+| `vestra-plugin check` | strict type check of the plugin's .ts files and tests/*.ts (then every use of an API member whose capability manifest.json does not declare: file:line, member, capability; fails on any; --json prints the findings as JSON) |
 | `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 |
@@ -3114,6 +3154,7 @@ Exit codes: 0 on success, 1 when a command failed for any of the directories (ea
 
 - **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.
+- **Capabilities.** After the type check, `check` reports every use of an API member whose capability `manifest.json` does not declare (`file:line:column`, the member, the capability, the request) and fails; `build` and `pack` run `check` first. Only the plugin's own code is checked, not `tests/`. The same check runs in the editor (Capabilities). `check --json` prints, instead of the text, one JSON array with an entry per plugin directory: `directory`, `plugin`, `findings` (each with `file` (absolute), `line` and `column` (1-based), `start` and `length` (the member's name as a UTF-16 offset and length in the file, as TypeScript counts), `api`, `capability`, `method`, `message`, and `requiredBy` when the capability is another one's **Also needs**) and `error` when the directory failed.
 - **`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).
 
@@ -5730,7 +5771,8 @@ interface SubtitleConditional {
 ### Subtitles
 
 `plugin.subtitles`: tracks, uploads and style. Reading needs
-`subtitles.read`, changes need `subtitles.control`.
+`subtitles.read`; changes need `subtitles.control` and also
+`subtitles.read`, since they read the current selection first.
 
 ```ts
 interface Subtitles {
@@ -7892,8 +7934,11 @@ interface CapabilityInfo {
 
 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.
+store's wording. Built from the player's own capability table (its
+`src/host/capabilities.json`, copied into the SDK) and the requests each
+member sends, the same rule `vestra-plugin check` and the SDK's
+TypeScript plugin apply; the player's tests check that the copy is
+current.
 
 A member not listed under any capability needs none (`plugin.tools`,
 `plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui`,

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.25: 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.
+> @vestra-player/sdk 1.5.26: 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**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-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: L2172–2238.
+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: L2195–2261.
 
 **main.ts**
 
@@ -76,9 +76,9 @@ export default async function activate(plugin: Plugin) {
 - `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: L2239–2281.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2262–2320.
 
-**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: L1635–1823; TestHost: L7019.
+**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: L1658–1846; TestHost: L7061.
 
 **Command line**
 
@@ -106,39 +106,39 @@ export default async function activate(plugin: Plugin) {
 - `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`
-- Others: PluginError, llms-full.txt L3190.
+- Others: PluginError, llms-full.txt L3231.
 
 ## Reference
 
 - [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–385; Commands, menus and key bindings L386–483; Playback state, controls and sources L484–629; Video and audio processing L630–708; Windows, panels, settings pages, dialogs and the OSD L709–997
-- How-to: Keep a slider responsive while dragging L998–1172; Remember a window's state between runs L1173–1302; Translate a plugin L1303–1486; Migrate a plugin to English source text L1487–1634; Test a plugin L1635–1823; Publish a plugin L1824–1912; Migrating off package rollback (1.5.16, removed in 1.5.17) L1913–1988
-- Guidelines: Interface guidelines L1989–2073; Menu guidelines L2074–2171
-- Reference: Manifest L2172–2238; Capabilities L2239–2281; Limits L2282–2386; Commands, menus and bindings L2387–2855; Platforms L2856–2884; Theme L2885–3091; Command line L3092–3147
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3148–6854
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6855–8257
+- Tutorials: Getting started L9–237
+- Concepts: How a plugin runs L238–408; Commands, menus and key bindings L409–506; Playback state, controls and sources L507–652; Video and audio processing L653–731; Windows, panels, settings pages, dialogs and the OSD L732–1020
+- How-to: Keep a slider responsive while dragging L1021–1195; Remember a window's state between runs L1196–1325; Translate a plugin L1326–1509; Migrate a plugin to English source text L1510–1657; Test a plugin L1658–1846; Publish a plugin L1847–1935; Migrating off package rollback (1.5.16, removed in 1.5.17) L1936–2011
+- Guidelines: Interface guidelines L2012–2096; Menu guidelines L2097–2194
+- Reference: Manifest L2195–2261; Capabilities L2262–2320; Limits L2321–2425; Commands, menus and bindings L2426–2894; Platforms L2895–2923; Theme L2924–3130; Command line L3131–3188
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3189–6896
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6897–8302
 
 ## API
 
 Where each module of `plugin` (`plugin.<module>`) is declared:
 
-- Plugin L3382, Scope L3251, PluginError L3190, Disposable L3163
-- Commands L3594; Windows L3824; Panels L4467; Dialogs L4753; Player L5220; video: VideoFilter L5527, VideoView L5590, RenderOptions L5632; audio: AudioFilter L5551; Subtitles L5730; media: MediaCapture L5890; Resolvers L5995; Packages L6237; Osd L5463; Host L5394; Clipboard L6369; Power L6389; Tools L6422; Storage L6465; System L6552; Secrets L6570; window: MainWindow L4590; App L4671; Bindings L6339; Ui L3699; Timeline L4547; Drops L4123; Appearance L4152; I18n L4294; Settings L4400.
+- Plugin L3423, Scope L3292, PluginError L3231, Disposable L3204
+- Commands L3635; Windows L3865; Panels L4508; Dialogs L4794; Player L5261; video: VideoFilter L5568, VideoView L5631, RenderOptions L5673; audio: AudioFilter L5592; Subtitles L5771; media: MediaCapture L5932; Resolvers L6037; Packages L6279; Osd L5504; Host L5435; Clipboard L6411; Power L6431; Tools L6464; Storage L6507; System L6594; Secrets L6612; window: MainWindow L4631; App L4712; Bindings L6381; Ui L3740; Timeline L4588; Drops L4164; Appearance L4193; I18n L4335; Settings L4441.
 
 ## Examples
 
 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. L8681–8770
-- blur: A tool window with one slider that blurs the playing video. L8771–9032
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L9033–9365
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9366–9550
-- panel-menu: A sidebar panel with its own right-click menu. L9551–9756
-- menus: Radio menu items, separator groups and a menu item whose title changes. L9757–9916
-- theme-widgets: A tool window drawn with the player's theme and widgets. L9917–10080
-- markdown: A window that shows a Markdown document. L10081–10275
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L10276–10443
+- hello: The README Quick start: one menu command and an on-screen message. L8726–8815
+- blur: A tool window with one slider that blurs the playing video. L8816–9077
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L9078–9410
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9411–9595
+- panel-menu: A sidebar panel with its own right-click menu. L9596–9801
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9802–9961
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9962–10125
+- markdown: A window that shows a Markdown document. L10126–10320
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L10321–10488
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.25",
+  "version": "1.5.26",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {
@@ -24,6 +24,10 @@
       "types": "./dist/player-runtime.d.ts",
       "default": "./dist/player-runtime.js"
     },
+    "./ts-plugin": {
+      "types": "./ts-plugin/index.d.ts",
+      "default": "./ts-plugin/index.js"
+    },
     "./llms.txt": "./llms.txt",
     "./llms-full.txt": "./llms-full.txt",
     "./package.json": "./package.json"
@@ -35,6 +39,7 @@
     "dist",
     "bin",
     "slint",
+    "ts-plugin",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -43,6 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
+    "capabilities:sync": "node scripts/capabilities-sync.mjs",
     "check": "tsc -p tsconfig.check.json",
     "doc-lint": "node scripts/doc-lint.mjs",
     "docs": "typedoc",
@@ -50,8 +56,8 @@
     "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\"",
+    "format": "prettier --write \"{src,test,bin,scripts,examples}/**/*.{ts,mjs}\" ts-plugin/index.js ts-plugin/index.d.ts 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}\" ts-plugin/index.js ts-plugin/index.d.ts package.json tsconfig.json tsconfig.check.json typedoc.json .oxlintrc.json examples/tsconfig.json \"examples/*/package.json\"",
     "lint": "oxlint --deny-warnings",
     "pack:check": "node scripts/check-pack.mjs",
     "pack:smoke": "node scripts/smoke-pack.mjs",

package/ts-plugin/index.d.ts

@@ -0,0 +1,8 @@
+// @vestra-player/sdk/ts-plugin: the TypeScript language-service plugin. List
+// it in tsconfig.json; it is not meant to be imported.
+import type ts from "typescript";
+
+declare function init(modules: {
+  typescript: typeof ts;
+}): ts.server.PluginModule;
+export = init;

package/ts-plugin/index.js

@@ -0,0 +1,6 @@
+// @vestra-player/sdk/ts-plugin: the TypeScript server loads language-service
+// plugins with require() and Node 10 resolution (no package.json "exports"),
+// hence this CommonJS directory. The plugin itself is dist/ts-plugin.js, an
+// ES module without top-level await, which require() loads (Node 22.12+).
+"use strict";
+module.exports = require("../dist/ts-plugin.js").default;

package/ts-plugin/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}