@vestra-player/sdk 1.5.25 → 1.5.26

package/dist/host-capabilities.js

@@ -0,0 +1,360 @@
+// "then" is a field of the player's IfDeclared rule, not a thenable.
+/* oxlint-disable unicorn/no-thenable */
+/** @internal */
+export const HOST_CAPABILITIES = {
+    about: "Generated from src/host/src/capabilities/ (VESTRA_UPDATE_CAPABILITIES=1 cargo test capabilities); do not edit. A method's needs: null (none), a capability name, {param, cases, otherwise} (by a string parameter) or {ifDeclared, then, otherwise}. A method name ending in .* covers the prefix's other methods.",
+    apiVersion: "vestra/1",
+    capabilities: [
+        {
+            label: "Provide audio and video it generates itself",
+            methods: [
+                { name: "producer.prepare", needs: "producer.av" },
+                { name: "producer.state", needs: "producer.av" },
+                { name: "producer.release", needs: "producer.av" },
+                { name: "producer.ack", needs: "producer.av" },
+                { name: "producer.declareInput", needs: "producer.av" },
+                { name: "producer.ackInput", needs: "producer.av" },
+            ],
+            name: "producer.av",
+            requires: ["playback.control"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read what is playing and the position",
+            methods: [
+                { name: "source.state", needs: "playback.read" },
+                { name: "processing.state", needs: "playback.read" },
+                { name: "playback.stats", needs: "playback.read" },
+                { name: "player.chapters", needs: "playback.read" },
+                { name: "player.audioDevices", needs: "playback.read" },
+                { name: "timeline.marks", needs: "playback.read" },
+            ],
+            name: "playback.read",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Open media, control playback, keep the computer awake",
+            methods: [
+                { name: "playback.set", needs: "playback.control" },
+                { name: "source.submit", needs: "playback.control" },
+                {
+                    name: "source.operation",
+                    needs: {
+                        ifDeclared: "playback.control",
+                        otherwise: "playback.read",
+                        then: "playback.control",
+                    },
+                },
+                { name: "audio.addTrack", needs: "playback.control" },
+                { name: "audio.selectTrack", needs: "playback.control" },
+                { name: "player.setLoop", needs: "playback.control" },
+                { name: "player.setAudioDevice", needs: "playback.control" },
+                { name: "player.step", needs: "playback.control" },
+                { name: "player.setStepSeek", needs: "playback.control" },
+                { name: "power.preventSleep", needs: "playback.control" },
+                { name: "sequence.set", needs: "playback.control" },
+                { name: "sequence.step", needs: "playback.control" },
+            ],
+            name: "playback.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Resolve online video addresses",
+            methods: [
+                { name: "sourceResolvers.register", needs: "source.resolve" },
+                { name: "sourceResolvers.unregister", needs: "source.resolve" },
+                { name: "sourceResolvers.respond", needs: "source.resolve" },
+                { name: "sourceResolvers.*", needs: "source.resolve" },
+            ],
+            name: "source.resolve",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Receive playback changes as they happen",
+            methods: [
+                {
+                    name: "events.subscribe",
+                    needs: {
+                        cases: {
+                            "bindings.changed": "bindings.manage",
+                            "packages.changed": null,
+                        },
+                        otherwise: "events",
+                        param: "event",
+                    },
+                },
+                {
+                    name: "events.unsubscribe",
+                    needs: {
+                        cases: {
+                            "bindings.changed": "bindings.manage",
+                            "packages.changed": null,
+                        },
+                        otherwise: "events",
+                        param: "event",
+                    },
+                },
+            ],
+            name: "events",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Add menu commands and shortcuts",
+            methods: [
+                { name: "commands.register", needs: "commands" },
+                { name: "commands.update", needs: "commands" },
+                { name: "commands.unregister", needs: "commands" },
+                { name: "host.run", needs: "commands" },
+            ],
+            name: "commands",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Open tool windows",
+            methods: [
+                { name: "ui.open", needs: "ui.window" },
+                { name: "ui.set", needs: "ui.window" },
+                { name: "ui.show", needs: "ui.window" },
+                { name: "ui.close", needs: "ui.window" },
+            ],
+            name: "ui.window",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show panels in the bottom bar, the sidebar or behind the video",
+            methods: [
+                { name: "ui.mount", needs: "ui.mount" },
+                { name: "ui.setMount", needs: "ui.mount" },
+                { name: "ui.unmount", needs: "ui.mount" },
+                { name: "ui.interaction", needs: "ui.mount" },
+                { name: "ui.menu", needs: "ui.mount" },
+                { name: "layout.state", needs: "ui.mount" },
+                { name: "layout.set", needs: "ui.mount" },
+            ],
+            name: "ui.mount",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show file pickers and confirmations",
+            methods: [
+                { name: "dialogs.open", needs: "ui.dialog" },
+                { name: "dialogs.confirm", needs: "ui.dialog" },
+            ],
+            name: "ui.dialog",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Install, uninstall and disable other plugins",
+            methods: [{ name: "packages.*", needs: "plugins.manage" }],
+            name: "plugins.manage",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Process the picture (filters, shaders)",
+            methods: [
+                {
+                    name: "processing.replace",
+                    needs: {
+                        cases: { video: "processing.video" },
+                        otherwise: "processing.audio",
+                        param: "stage",
+                    },
+                },
+                {
+                    name: "processing.operation",
+                    needs: {
+                        cases: { video: "processing.video" },
+                        otherwise: "processing.audio",
+                        param: "stage",
+                    },
+                },
+                { name: "video.view.set", needs: "processing.video" },
+                { name: "video.view.release", needs: "processing.video" },
+                { name: "video.render.set", needs: "processing.video" },
+                { name: "video.render.release", needs: "processing.video" },
+            ],
+            name: "processing.video",
+            requires: ["playback.read"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Process the sound",
+            methods: [],
+            name: "processing.audio",
+            requires: ["playback.read", "events"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read subtitles",
+            methods: [{ name: "subtitles.state", needs: "subtitles.read" }],
+            name: "subtitles.read",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Load and change subtitles",
+            methods: [{ name: "subtitles.*", needs: "subtitles.control" }],
+            name: "subtitles.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Take snapshots and export clips",
+            methods: [
+                { name: "snapshot.state", needs: "media.read" },
+                { name: "jobs.state", needs: "media.read" },
+                { name: "jobs.operation", needs: "media.read" },
+            ],
+            name: "media.read",
+            requires: ["media.control"],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Take snapshots and export clips",
+            methods: [
+                { name: "snapshot.*", needs: "media.control" },
+                { name: "jobs.*", needs: "media.control" },
+            ],
+            name: "media.control",
+            requires: ["media.read"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show messages on the video",
+            methods: [
+                { name: "osd.show", needs: "ui.osd" },
+                { name: "osd.panel", needs: "ui.osd" },
+            ],
+            name: "ui.osd",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read and write the clipboard",
+            methods: [
+                { name: "clipboard.readText", needs: "clipboard" },
+                { name: "clipboard.writeText", needs: "clipboard" },
+                { name: "clipboard.writeImage", needs: "clipboard" },
+            ],
+            name: "clipboard",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Adjust the main window (size, on top, picture-in-picture)",
+            methods: [
+                { name: "window.setVideoArea", needs: "window.control" },
+                { name: "window.setAlwaysOnTop", needs: "window.control" },
+                { name: "window.setCursorAutoHide", needs: "window.control" },
+                { name: "window.setPictureInPicture", needs: "window.control" },
+            ],
+            name: "window.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Change all shortcuts",
+            methods: [
+                { name: "bindings.list", needs: "bindings.manage" },
+                { name: "bindings.set", needs: "bindings.manage" },
+                { name: "bindings.reset", needs: "bindings.manage" },
+            ],
+            name: "bindings.manage",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Show marks on the progress bar",
+            methods: [{ name: "timeline.set", needs: "timeline.marks" }],
+            name: "timeline.marks",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Receive files dropped on the player",
+            methods: [
+                { name: "drops.provide", needs: "ui.drop" },
+                { name: "drops.withdraw", needs: "ui.drop" },
+                { name: "drops.listen", needs: "ui.drop" },
+            ],
+            name: "ui.drop",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Add pages to the Options window",
+            methods: [{ name: "settings.*", needs: "ui.settings" }],
+            name: "ui.settings",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Change the player's palette",
+            methods: [
+                { name: "appearance.set", needs: "ui.theme" },
+                { name: "appearance.setLanguage", needs: "ui.theme" },
+            ],
+            name: "ui.theme",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Store sign-in details in the system keychain",
+            methods: [
+                { name: "secrets.get", needs: "secrets" },
+                { name: "secrets.set", needs: "secrets" },
+                { name: "secrets.delete", needs: "secrets" },
+            ],
+            name: "secrets",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+    ],
+    uncapable: [
+        { name: "packages.list", needs: null },
+        { name: "window.state", needs: null },
+        { name: "system.reveal", needs: null },
+        { name: "system.openPath", needs: null },
+        { name: "system.openUrl", needs: null },
+        { name: "app.system", needs: null },
+        { name: "ui.markdownScan", needs: null },
+        { name: "storage.session.get", needs: null },
+        { name: "storage.session.set", needs: null },
+        { name: "storage.session.delete", needs: null },
+        { name: "storage.session.keys", needs: null },
+    ],
+};

package/dist/player-runtime.d.ts

@@ -12,6 +12,7 @@ export type { PluginInstance, PluginManifest } from "./plugin/index.ts";
 export { HostError } from "./wire.ts";
 export type { Json, Transport } from "./wire.ts";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.ts";
+export { HOST_CAPABILITIES } from "./host-capabilities.ts";
 export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.ts";
 export { BINDING_INPUTS } from "./plugin/bindings.ts";
 export { OSD_LIMITS } from "./plugin/osd.ts";

package/dist/player-runtime.js

@@ -10,6 +10,7 @@
 export { createPlugin } from "./plugin/index.js";
 export { HostError } from "./wire.js";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.js";
+export { HOST_CAPABILITIES } from "./host-capabilities.js";
 export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.js";
 export { BINDING_INPUTS } from "./plugin/bindings.js";
 export { OSD_LIMITS } from "./plugin/osd.js";

package/dist/plugin/types.d.ts

@@ -4390,7 +4390,8 @@ export interface SubtitleConditional {
 }
 /**
  * `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.
  *
  * @example Load an SRT file as the secondary subtitle
  * ```ts

package/dist/ts-plugin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The TypeScript language-service plugin `@vestra-player/sdk/ts-plugin`: the
+ * capability checker of `vestra-plugin check` in the editor. A use of an API
+ * member whose capability `manifest.json` does not declare is an error at
+ * the member, with the quick fix "Add '<capability>' to manifest.json".
+ *
+ * A project enables it in its tsconfig.json:
+ *
+ *   { "compilerOptions": { "plugins": [{ "name": "@vestra-player/sdk/ts-plugin" }] } }
+ *
+ * The editor must run the project's own TypeScript (VS Code: "TypeScript:
+ * Select TypeScript Version" → "Use Workspace Version"); `tsc` ignores
+ * language-service plugins, which is why `vestra-plugin check` runs the same
+ * checker. The manifest is the nearest `manifest.json` above the file; files
+ * in its `tests/`, `node_modules/`, `dist/` and `vendor/` are not checked.
+ *
+ * @internal
+ */
+import type TS from "typescript";
+/** @internal The plugin factory tsserver calls (`ts-plugin/index.js`). */
+export default function init(modules: {
+    typescript: typeof TS;
+}): TS.server.PluginModule;

package/dist/ts-plugin.js

@@ -0,0 +1,135 @@
+import { addCapabilityEdit, CAPABILITY_DIAGNOSTIC, findUndeclaredCapabilities, isPluginSource, } from "./capability-check.js";
+const FIX_NAME = "vestraAddCapability";
+/** The nearest manifest.json at or above a file, with its capabilities. */
+function manifestFor(ts, file) {
+    let directory = file.replaceAll("\\", "/");
+    for (;;) {
+        const parent = directory.slice(0, directory.lastIndexOf("/"));
+        if (!parent || parent === directory)
+            return undefined;
+        directory = parent;
+        const path = `${directory}/manifest.json`;
+        if (!ts.sys.fileExists(path))
+            continue;
+        try {
+            const manifest = JSON.parse(ts.sys.readFile(path) ?? "");
+            if (!Array.isArray(manifest.capabilities))
+                return undefined;
+            return {
+                path,
+                directory,
+                capabilities: manifest.capabilities.filter((each) => typeof each === "string"),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * The manifest's text for the quick fix. The TypeScript server applies a
+ * code fix only to files it knows, and editors do not hand it JSON files
+ * (VS Code does not), so the manifest is made known first; its text is then
+ * the server's: an open buffer when the editor shares one, else the file on
+ * disk (VS Code: the saved manifest, not unsaved edits).
+ */
+function manifestText(ts, info, path) {
+    const service = info.project?.projectService;
+    const script = service && ts.server?.toNormalizedPath
+        ? service.getOrCreateScriptInfoForNormalizedPath(ts.server.toNormalizedPath(path), false)
+        : undefined;
+    const snapshot = script?.getSnapshot();
+    return snapshot
+        ? snapshot.getText(0, snapshot.getLength())
+        : ts.sys.readFile(path);
+}
+/** @internal The plugin factory tsserver calls (`ts-plugin/index.js`). */
+export default function init(modules) {
+    const ts = modules.typescript;
+    return {
+        create(info) {
+            const service = info.languageService;
+            const log = (message) => info.project?.projectService?.logger?.info(`[@vestra-player/sdk/ts-plugin] ${message}`);
+            const findings = (file) => {
+                const manifest = manifestFor(ts, file);
+                const program = service.getProgram();
+                if (!manifest || !program || !isPluginSource(manifest.directory, file))
+                    return [];
+                try {
+                    return findUndeclaredCapabilities(ts, program, {
+                        files: [file],
+                        capabilities: manifest.capabilities,
+                    });
+                }
+                catch (error) {
+                    log(`check failed: ${error.stack ?? String(error)}`);
+                    return [];
+                }
+            };
+            const proxy = Object.create(null);
+            for (const key of Object.keys(service)) {
+                const member = service[key];
+                proxy[key] =
+                    typeof member === "function" ? member.bind(service) : member;
+            }
+            proxy.getSemanticDiagnostics = (file) => {
+                const prior = service.getSemanticDiagnostics(file);
+                const source = service.getProgram()?.getSourceFile(file);
+                return [
+                    ...prior,
+                    ...findings(file).map((finding) => ({
+                        file: source,
+                        start: finding.start,
+                        length: finding.length,
+                        messageText: finding.message,
+                        category: ts.DiagnosticCategory.Error,
+                        code: CAPABILITY_DIAGNOSTIC,
+                        source: "vestra",
+                    })),
+                ];
+            };
+            proxy.getSupportedCodeFixes = (file) => [
+                ...service.getSupportedCodeFixes(file),
+                String(CAPABILITY_DIAGNOSTIC),
+            ];
+            proxy.getCodeFixesAtPosition = (file, start, end, errorCodes, format, preferences) => {
+                const prior = service.getCodeFixesAtPosition(file, start, end, errorCodes, format, preferences);
+                if (!errorCodes.includes(CAPABILITY_DIAGNOSTIC))
+                    return prior;
+                const manifest = manifestFor(ts, file);
+                if (!manifest)
+                    return prior;
+                const text = manifestText(ts, info, manifest.path);
+                if (text === undefined)
+                    return prior;
+                const wanted = new Set(findings(file)
+                    .filter((finding) => finding.start <= end && finding.start + finding.length >= start)
+                    .map((finding) => finding.capability));
+                const fixes = [];
+                for (const capability of wanted) {
+                    const edit = addCapabilityEdit(ts, text, capability);
+                    if (!edit)
+                        continue;
+                    fixes.push({
+                        fixName: FIX_NAME,
+                        description: `Add '${capability}' to manifest.json`,
+                        changes: [
+                            {
+                                fileName: manifest.path,
+                                textChanges: [
+                                    {
+                                        span: { start: edit.start, length: edit.length },
+                                        newText: edit.newText,
+                                    },
+                                ],
+                            },
+                        ],
+                    });
+                }
+                return [...prior, ...fixes];
+            };
+            log("enabled");
+            return proxy;
+        },
+    };
+}