@vestra-player/sdk 1.5.24 → 1.5.26

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.5.26
+
+**Who must change: authors whose plugin uses a member without one of the capabilities it needs, and only to `check`, `build` or `pack` again.** No API changes, `apiVersion` stays `vestra/1`, no player version needed, and packages already built keep running as before: the player decides at run time exactly as it did. What changes is that `vestra-plugin check` (and so `build` and `pack`) now fails on such a use, including uses that never failed at run time: a listener (`onChange`) without `events` never fires instead of failing; a subtitle change (`select`, `load`, `remove`, `setStyle`) without `subtitles.read` fails only when it reads the current selection; a capability's **Also needs** (`processing.video` without `playback.read`) was documented but not enforced. Such a plugin packed with 1.5.25 and stops packing with 1.5.26 until the missing capability is added to `manifest.json` (or the use removed). The player's built-in plugins and the plugin repository's plugins were checked with this release: no findings.
+
+- **Undeclared capabilities are caught while writing and packing** (user ruling of 2026-10-27, doc/process/rounds/2026-10-capability-check.md in the player repository): every use of an API member whose capability `manifest.json` does not declare, with `file:line:column`, the member, the capability and the request. Type-aware: found through aliases, destructuring, parameters typed `Player` and so on; not through computed names, `any` or plain JavaScript. A member also needs its capabilities' **Also needs** (`requires`). Tests are not checked.
+  - **`vestra-plugin check`** runs it after the type check and fails on any finding; `build` and `pack` run `check` first. **`check --json`** prints the findings as JSON.
+  - **`@vestra-player/sdk/ts-plugin`**, a TypeScript language-service plugin: the same findings as errors in the editor, with the quick fix "Add '<capability>' to manifest.json". List it in `tsconfig.json` (`"plugins": [{ "name": "@vestra-player/sdk/ts-plugin" }]`) and use the workspace's TypeScript (VS Code: **Use Workspace Version**).
+- **One rule with the player.** The SDK carries a copy of the player's generated capability table (`src/host/capabilities.json`: which request needs which capability, by event name or processing stage where it depends on one) and the requests each member sends. `CAPABILITY_INFO` is now built from them; its contents are unchanged. `HOST_CAPABILITIES` (`@vestra-player/sdk/runtime`, for the player's agreement test) is the copy.
+- Docs: *Capabilities* gains *Catching a missing capability*; *Getting started* adds the `tsconfig.json` with the plugin and the VS Code step; *Command line* (the rule and `--json`); *Subtitles* and *Capabilities*: changes also need `subtitles.read` (they read the current selection first; the table now says so). `examples/tsconfig.json` lists the plugin. `llms.txt` and `llms-full.txt` regenerated.
+
+## 1.5.25
+
+**Who must change: nobody.** Plugins built on earlier SDKs keep working unchanged: `plugin.storage.json` and every other API do what they did. Additive; `apiVersion` stays `vestra/1`. The addition needs player 0.5.5.
+
+- **`plugin.storage.session`** (`SessionStorage`, player 0.5.5; user ruling of 2026-10-27, after Chrome's `chrome.storage.session`): `get(key)`, `set(key, value)`, `delete(key)` and `keys()` of JSON values that live as long as the **player**, not the plugin's process. They survive every restart of the plugin within one player session (a reload, also of a development load, an upgrade, a crash, a failed start) and are cleared when the user disables or uninstalls the plugin, and when the player quits. Per plugin, no capability. Keys are 1–1024 bytes of well-formed text; a plugin's keys, values (as compact JSON) and 128 bytes per key are at most 1 MiB together, and a `set` beyond fails with `limit` and changes nothing. One value must also fit in one 1 MiB message. A value `JSON.stringify` cannot write, or one with a lone surrogate in a string, fails with `invalid`; the order of an object's properties is not kept; `get` returns `undefined` for a missing key. Each `set` is one acknowledged request, without debounce. Players before 0.5.5 reject the calls with `unsupported`, so set `"minPlayerVersion": "0.5.5"`.
+- **`SESSION_STORAGE_LIMITS`** (`@vestra-player/sdk/testing` and `/runtime`): `keyBytes` 1024, `bytes` 1 MiB, `entryBytes` 128.
+- **`TestHost.sessionStorage`** (the player's store for the plugin, with the player's key rule and quota, objects stored with sorted properties as the player returns them) and **`startPlugin(..., { sessionStorage })`** to start with the values an earlier run left, to test a restart within one player session. `TestHost` now refuses any request over the 1 MiB message limit with `limit`, as the plugin runner does.
+- Docs: *How a plugin runs* gains *Restarts: activate can run more than once*: when the player restarts a plugin's process, and "keep state that must survive a restart in session storage (or persistent storage)", with a table of what survives what. *Test a plugin* (testing a restart with session values), *Reference: limits* (`SESSION_STORAGE_LIMITS`). `llms.txt` and `llms-full.txt` regenerated.
+
 ## 1.5.24
 
 **Who must change: nobody.** Plugins built on earlier SDKs keep working unchanged: `when: "interlaced"` and `when: "all"` do what they did. Additive; `apiVersion` stays `vestra/1`. The addition needs player 0.5.4.

package/bin/vestra-plugin.mjs

@@ -11,6 +11,9 @@
  * directory. Works in any project that depends on @vestra-player/sdk.
  *
  *   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)
  *   build   check, then write dist/: .ts → .js with types stripped, other
  *           package files copied, dist/manifest.json with `version`
  *   test    node --test on tests/*.test.{ts,mjs}
@@ -88,6 +91,9 @@ const i18n = await import(pathToFileURL(join(sdkRoot, "dist/i18n.js")).href);
 const i18nTools = await import(
   pathToFileURL(join(sdkRoot, "dist/i18n-tools.js")).href
 );
+const capabilityCheck = await import(
+  pathToFileURL(join(sdkRoot, "dist/capability-check.js")).href
+);
 const SDK = "@vestra-player/sdk";
 
 /** Never part of a production package. */
@@ -234,7 +240,7 @@ function run(command, args, options = {}) {
 }
 
 /** npm dependencies are installed from the lock file when missing. */
-function dependencies(target) {
+function dependencies(target, quiet = false) {
   const deps = {
     ...target.packageJson.dependencies,
     ...target.packageJson.devDependencies,
@@ -244,12 +250,15 @@ function dependencies(target) {
     present(join(target.directory, "node_modules"))
   )
     return;
-  console.log(`${target.name}: installing dependencies (npm ci)`);
+  (quiet ? console.error : console.log)(
+    `${target.name}: installing dependencies (npm ci)`,
+  );
   // npm is npm.cmd on Windows, which spawn only runs through a shell.
   if (
     run("npm", ["ci", "--no-audit", "--no-fund"], {
       cwd: target.directory,
       shell: process.platform === "win32",
+      ...(quiet ? { stdio: ["ignore", process.stderr, "inherit"] } : {}),
     }) !== 0
   )
     fail(
@@ -296,10 +305,10 @@ function checkConfig(target, sources) {
   };
 }
 
-async function check(target) {
-  for (const hint of target.hints ?? [])
-    console.log(`${target.name}: hint: ${hint}`);
-  dependencies(target);
+async function check(target, report = null) {
+  const say = report ? () => {} : (line) => console.log(line);
+  for (const hint of target.hints ?? []) say(`${target.name}: hint: ${hint}`);
+  dependencies(target, !!report);
   const own = (await files(target.directory)).filter(
     (file) => isTypeScript(file) || file.endsWith(".mts"),
   );
@@ -312,20 +321,41 @@ async function check(target) {
     join(target.directory, file),
   );
   if (!sources.length) {
-    console.log(`${target.name}: no TypeScript to check`);
+    say(`${target.name}: no TypeScript to check`);
+    report?.push({ plugin: target.name, findings: [] });
     return;
   }
   const tsc = compiler("typescript/lib/tsc.js");
   const scratch = await mkdtemp(join(tmpdir(), "vestra-plugin-check-"));
+  let findings;
   try {
     const config = join(scratch, "tsconfig.json");
     await writeFile(config, JSON.stringify(checkConfig(target, sources)));
-    if (run(process.execPath, [tsc, "-p", config]) !== 0)
+    if (
+      run(process.execPath, [tsc, "-p", config], {
+        stdio: report ? ["ignore", process.stderr, "inherit"] : "inherit",
+      }) !== 0
+    )
       fail(`${target.name}: type check failed`);
+    say(`${target.name}: type check passed (${sources.length} files)`);
+    findings = await capabilityFindings(target, config);
   } finally {
     await rm(scratch, { recursive: true, force: true });
   }
-  console.log(`${target.name}: type check passed (${sources.length} files)`);
+  if (report) report.push({ plugin: target.name, findings });
+  else
+    for (const finding of findings)
+      console.error(
+        `${relative(process.cwd(), finding.file) || finding.file}:${finding.line}:${finding.column}: ${finding.message} (request ${finding.method})`,
+      );
+  if (findings.length) {
+    const missing = [...new Set(findings.map((each) => each.capability))];
+    fail(
+      `${target.name}: ${findings.length} use${findings.length === 1 ? "" : "s"} of undeclared capabilities; add ${missing.map((each) => `"${each}"`).join(", ")} to manifest.json "capabilities" (or stop using those members)`,
+    );
+  }
+  say(`${target.name}: capabilities declared for every API use`);
+  if (report) return;
   // Translation warnings never fail the check.
   if (present(join(target.directory, "locales"))) {
     try {
@@ -338,6 +368,37 @@ async function check(target) {
   }
 }
 
+/**
+ * Uses of API members whose capability the manifest does not declare, in
+ * the plugin's production files (not tests/), with the type check's
+ * compiler options (src/capability-check.ts).
+ */
+async function capabilityFindings(target, config) {
+  const ts = await typescript();
+  const parsed = ts.getParsedCommandLineOfConfigFile(
+    config,
+    {},
+    {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic: (diagnostic) =>
+        fail(
+          `${target.name}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")}`,
+        ),
+    },
+  );
+  const files = (await sourceFiles(target)).typescript.map((file) =>
+    join(target.directory, file),
+  );
+  if (!parsed || !files.length) return [];
+  const program = ts.createProgram(parsed.fileNames, parsed.options);
+  const capabilities = Array.isArray(target.manifest.capabilities)
+    ? target.manifest.capabilities
+    : [];
+  return capabilityCheck
+    .findUndeclaredCapabilities(ts, program, { files, capabilities })
+    .map((finding) => ({ ...finding, file: resolve(finding.file) }));
+}
+
 /** The plugin's own production .ts / .mts and .slint files. */
 async function sourceFiles(target) {
   const all = await files(target.directory);
@@ -703,6 +764,7 @@ async function pack(target, flag, outDirectory) {
 
 const USAGE = [
   "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...]",
 ].join("\n");
@@ -740,6 +802,12 @@ async function main() {
   }
   if (locales.length && subcommand !== "extract")
     fail("--locale applies to i18n extract");
+  const jsonIndex = args.indexOf("--json");
+  const report = jsonIndex >= 0 ? [] : null;
+  if (report) {
+    args.splice(jsonIndex, 1);
+    if (command !== "check") fail("--json applies to check");
+  }
   const flag = option("--version");
   const out = option("--out");
   const directories = args.length ? args : ["."];
@@ -747,11 +815,12 @@ async function main() {
     fail("--version applies to a single plugin");
   const failed = [];
   for (const directory of directories) {
+    const reported = report?.length ?? 0;
     try {
       const target = await plugin(directory);
       if (subcommand === "extract") await i18nExtract(target, locales);
       else if (subcommand === "check") await i18nCheck(target);
-      else if (command === "check") await check(target);
+      else if (command === "check") await check(target, report);
       else if (command === "build") await build(target, flag);
       else if (command === "pack") await pack(target, flag, out);
       else await test(target);
@@ -759,8 +828,14 @@ async function main() {
       if (!error.expected) throw error;
       console.error(`✖ ${error.message}`);
       failed.push(directory);
+      if (report) {
+        if (report.length === reported) report.push({ findings: [] });
+        report[reported].error = error.message;
+      }
     }
+    if (report) report[reported] = { directory, ...report[reported] };
   }
+  if (report) console.log(JSON.stringify(report, null, 2));
   if (failed.length) {
     console.error(
       `${subcommand ? `i18n ${subcommand}` : command} failed for: ${failed.join(", ")}`,

package/dist/api-requests.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which player requests each member of the plugin API sends: the SDK's half
+ * of the capability rule (the player's half, what each request needs, is
+ * `HOST_CAPABILITIES`). A member is written `Interface.member` as in
+ * `CAPABILITY_INFO`; members declared on `Scope` are written `Plugin.…`.
+ *
+ * List the requests that decide the member's capabilities: the one it
+ * sends to do its work, and for a listener the `events.subscribe` with its
+ * event name. A string parameter that the player's rule reads (`event`,
+ * `stage`) is given in `params`. `also: true` marks a request whose
+ * capability the member needs on top of its own (documented at the member,
+ * not listed in its capability's `CAPABILITY_INFO.apis`).
+ *
+ * Members that need no capability are left out, apart from a few that show
+ * a rule's "none" case. Members of objects that another listed member
+ * returns (a `Window` from `Windows.create`, a `Panel` from `Panels.mount`)
+ * are left out too: the call that created the object already needs the
+ * capability.
+ *
+ * Order matters for `CAPABILITY_INFO`: each capability lists its members in
+ * this table's order. test/capability-rules.test.ts checks every method and
+ * parameter against the player's table.
+ *
+ * @internal
+ */
+/** @internal One request a member sends. */
+export interface ApiRequest {
+    /** The wire method (`source.submit`). */
+    readonly method: string;
+    /** String parameters the player's rule for the method reads. */
+    readonly params?: Readonly<Record<string, string>>;
+    /** A further capability, documented at the member. */
+    readonly also?: true;
+}
+/** @internal */
+export declare const API_REQUESTS: Readonly<Record<string, readonly ApiRequest[]>>;

package/dist/api-requests.js

@@ -0,0 +1,143 @@
+/**
+ * Which player requests each member of the plugin API sends: the SDK's half
+ * of the capability rule (the player's half, what each request needs, is
+ * `HOST_CAPABILITIES`). A member is written `Interface.member` as in
+ * `CAPABILITY_INFO`; members declared on `Scope` are written `Plugin.…`.
+ *
+ * List the requests that decide the member's capabilities: the one it
+ * sends to do its work, and for a listener the `events.subscribe` with its
+ * event name. A string parameter that the player's rule reads (`event`,
+ * `stage`) is given in `params`. `also: true` marks a request whose
+ * capability the member needs on top of its own (documented at the member,
+ * not listed in its capability's `CAPABILITY_INFO.apis`).
+ *
+ * Members that need no capability are left out, apart from a few that show
+ * a rule's "none" case. Members of objects that another listed member
+ * returns (a `Window` from `Windows.create`, a `Panel` from `Panels.mount`)
+ * are left out too: the call that created the object already needs the
+ * capability.
+ *
+ * Order matters for `CAPABILITY_INFO`: each capability lists its members in
+ * this table's order. test/capability-rules.test.ts checks every method and
+ * parameter against the player's table.
+ *
+ * @internal
+ */
+const submit = [{ method: "source.submit" }, { method: "source.operation" }];
+const readsSubtitles = { method: "subtitles.state", also: true };
+const listen = (event, also) => also
+    ? { method: "events.subscribe", params: { event }, also }
+    : { method: "events.subscribe", params: { event } };
+/** @internal */
+export const API_REQUESTS = Object.freeze({
+    "Player.state": [{ method: "source.state" }],
+    "Player.refresh": [{ method: "source.state" }],
+    "Player.stats": [{ method: "playback.stats" }],
+    "Player.chapters": [{ method: "player.chapters" }],
+    "Player.audioDevices": [{ method: "player.audioDevices" }],
+    "Player.onChange": [listen("source.state")],
+    "Player.open": submit,
+    "Player.openStream": [
+        { method: "producer.prepare" },
+        { method: "source.submit", also: true },
+    ],
+    "Player.setPaused": submit,
+    "Player.seek": submit,
+    "Player.setRate": submit,
+    "Player.restart": submit,
+    "Player.close": submit,
+    "Player.scrub": submit,
+    "Player.setOutput": [{ method: "playback.set" }],
+    "Player.provideSequence": [{ method: "sequence.set" }],
+    "Player.next": [{ method: "sequence.step" }],
+    "Player.previous": [{ method: "sequence.step" }],
+    "Player.addAudioTrack": [{ method: "audio.addTrack" }],
+    "Player.selectAudioTrack": [{ method: "audio.selectTrack" }],
+    "Player.step": [{ method: "player.step" }],
+    "Player.setStepSeek": [{ method: "player.setStepSeek" }],
+    "Player.setLoop": [{ method: "player.setLoop" }],
+    "Player.setAudioDevice": [{ method: "player.setAudioDevice" }],
+    "Power.preventSleep": [{ method: "power.preventSleep" }],
+    "Subtitles.state": [{ method: "subtitles.state" }],
+    "Subtitles.onChange": [
+        listen("source.state"),
+        { method: "subtitles.state" },
+    ],
+    "Subtitles.refresh": [{ method: "subtitles.state" }],
+    // Changes read the current selection first (`refresh`), unless
+    // `ifCurrent` pins one; `load` always does.
+    "Subtitles.select": [{ method: "subtitles.select" }, readsSubtitles],
+    "Subtitles.load": [{ method: "subtitles.upload.begin" }, readsSubtitles],
+    "Subtitles.remove": [{ method: "subtitles.remove" }, readsSubtitles],
+    "Subtitles.setStyle": [{ method: "subtitles.style" }, readsSubtitles],
+    "Timeline.marks": [{ method: "timeline.marks" }],
+    "Timeline.onChange": [listen("timeline.changed")],
+    "Timeline.layer": [{ method: "timeline.set" }],
+    "MainWindow.onChange": [listen("window.state")],
+    "MainWindow.setVideoArea": [{ method: "window.setVideoArea" }],
+    "MainWindow.setAlwaysOnTop": [{ method: "window.setAlwaysOnTop" }],
+    "MainWindow.setCursorAutoHide": [{ method: "window.setCursorAutoHide" }],
+    "MainWindow.setPictureInPicture": [
+        { method: "window.setPictureInPicture" },
+    ],
+    "Appearance.onChange": [listen("appearance.changed")],
+    "Appearance.set": [{ method: "appearance.set" }],
+    "Appearance.setLanguage": [{ method: "appearance.setLanguage" }],
+    "Drops.provide": [{ method: "drops.provide" }],
+    "Panels.mount": [{ method: "ui.mount" }],
+    "Panels.bottom": [{ method: "layout.state" }],
+    "Panels.sidebar": [{ method: "layout.state" }],
+    "Panels.backdrop": [{ method: "layout.state" }],
+    "PanelSlot.onChange": [{ method: "layout.state" }, listen("window.state")],
+    "Panel.onChange": [{ method: "layout.state" }, listen("window.state")],
+    "Panel.onDrop": [{ method: "drops.listen" }],
+    "BackdropSlot.onChange": [
+        { method: "layout.state" },
+        listen("window.state"),
+    ],
+    "Resolvers.add": [{ method: "sourceResolvers.register" }],
+    "Resolvers.onFileTypesChange": [listen("resolvers.fileTypes")],
+    "Commands.add": [{ method: "commands.register" }],
+    "Host.run": [{ method: "host.run" }],
+    "Windows.create": [{ method: "ui.open" }],
+    "Dialogs.confirm": [{ method: "dialogs.confirm" }],
+    "Dialogs.openFile": [{ method: "dialogs.open" }],
+    "Dialogs.openFiles": [{ method: "dialogs.open" }],
+    "Dialogs.openDirectory": [{ method: "dialogs.open" }],
+    "Dialogs.saveFile": [{ method: "dialogs.open" }],
+    "Packages.list": [{ method: "packages.list" }],
+    "Packages.onChange": [listen("packages.changed")],
+    "Packages.validate": [{ method: "packages.validate" }],
+    "Packages.validateArchive": [{ method: "packages.validateArchive" }],
+    "Packages.setEnabled": [{ method: "packages.setEnabled" }],
+    "Packages.reload": [{ method: "packages.reload" }],
+    "Packages.uninstall": [{ method: "packages.uninstall" }],
+    "Plugin.video.filter": [
+        { method: "processing.replace", params: { stage: "video" } },
+        listen("source.state", true),
+    ],
+    "Plugin.video.view": [{ method: "video.view.set" }],
+    "Plugin.video.render": [{ method: "video.render.set" }],
+    "Plugin.audio.filter": [
+        { method: "processing.replace", params: { stage: "audio" } },
+    ],
+    "MediaCapture.capture": [
+        { method: "snapshot.state" },
+        { method: "snapshot.capture" },
+    ],
+    "Snapshot.export": [{ method: "jobs.state" }, { method: "jobs.start" }],
+    "Osd.show": [{ method: "osd.show" }],
+    "Osd.panel": [{ method: "osd.panel" }],
+    "Clipboard.readText": [{ method: "clipboard.readText" }],
+    "Clipboard.writeText": [{ method: "clipboard.writeText" }],
+    "Clipboard.writeImage": [{ method: "clipboard.writeImage" }],
+    "Bindings.list": [{ method: "bindings.list" }],
+    "Bindings.set": [{ method: "bindings.set" }],
+    "Bindings.reset": [{ method: "bindings.reset" }],
+    "Bindings.onChange": [listen("bindings.changed")],
+    "Settings.page": [{ method: "settings.register" }],
+    "Settings.show": [{ method: "settings.show" }],
+    "Secrets.get": [{ method: "secrets.get" }],
+    "Secrets.set": [{ method: "secrets.set" }],
+    "Secrets.delete": [{ method: "secrets.delete" }],
+});

package/dist/capabilities.d.ts

@@ -38,8 +38,11 @@ export 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`,
@@ -62,7 +65,7 @@ export declare const CAPABILITY_INFO: Readonly<Record<string, CapabilityInfo>>;
 /**
  * Manifest capabilities the player knows (`vestra/1`): the keys of
  * {@link CAPABILITY_INFO}, in the player's order. The same list as the
- * player's `host/src/plugins.rs`; the player's tests check that they agree.
+ * player's `host/capabilities.json`; the player's tests check that they agree.
  */
 export declare const CAPABILITIES: readonly string[];
 /** The plugin API version this SDK implements (`manifest.apiVersion`). */