@vestra-player/sdk 1.5.25 → 1.5.27

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.5.27
+
+**Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Plugins pick the fix up with the player's next SDK upgrade (the player builds the `plugin` object with its own copy); nothing in a plugin changes.
+
+- **Generated streams reach their full frame rate on Windows.** A stream from `openStream` or a file resolver (the NES emulator: one 1/60 s picture per `frame()`) played at 23–26 frames a second on Windows instead of 60. The SDK asked the player how much audio the sound card had played, rendered at most one frame, and waited 5 ms before asking again; Windows rounds that wait up to its 15.6 ms timer tick, and with the round trip one pass took about 40 ms, so one frame per pass could not keep up. macOS timers are about 1 ms, which hid it. Each pass now calls `frame()` as many times in a row as it takes to refill the whole lead (about 50 ms of audio, unchanged, so latency is unchanged), at most 16 times, and stops early when a frame carries no audio; and a pass that rendered frames and already took longer than 5 ms is followed at once instead of after another timer tick. A pass that rendered nothing (paused, lead full) still waits 5 ms after it ends, so an idle or paused stream asks the player no more often than before. Measured against a real-time audio clock with the NES core and its homebrew ROM: with a 15–30 ms round trip 1.5.26 rendered 22–32 frames a second and let the device run dry, 1.5.27 renders 60 and keeps it fed; only a round trip near 50 ms (the whole lead) still lets it run dry now and then. Controls (start, pause, seek) still apply between frames and never while one renders, and `stop()` still ends after the frame being rendered.
+- Docs: *Example: signal generator* says `frame()` may be called several times back to back. `llms.txt` and `llms-full.txt` regenerated.
+
+## 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.

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`). */