@vestra-player/sdk 1.5.24 → 1.5.26

package/dist/plugin/testing.d.ts

@@ -7,7 +7,7 @@ import type { BuiltinCommand, BuiltinSubmenu } from "../commands.ts";
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.ts";
 import type { CapabilityInfo } from "../capabilities.ts";
 import { OSD_LIMITS } from "./osd.ts";
-import { SECRET_LIMITS } from "./services.ts";
+import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.ts";
 import { BINDING_INPUTS } from "./bindings.ts";
 import { THEME_PALETTES } from "../palettes.ts";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./values.ts";
@@ -34,6 +34,8 @@ export { MESSAGE_LIMIT };
 export { OSD_LIMITS };
 /** The player's limits on stored secrets. */
 export { SECRET_LIMITS };
+/** The player's limits on `plugin.storage.session`. */
+export { SESSION_STORAGE_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -1072,6 +1074,18 @@ export declare class TestHost implements Transport {
      * new name fails `limit` once 256 names are stored.
      */
     readonly secrets: Map<string, string>;
+    /**
+     * `plugin.storage.session`: key → value, as the player keeps them. Preset
+     * entries to simulate values an earlier run of the plugin stored in the
+     * same player session, or pass `startPlugin(..., { sessionStorage })`.
+     * Like the player, a key is 1–1024 bytes, a `set` that would make the
+     * entries larger than 1 MiB (keys, values as compact JSON and
+     * `SESSION_STORAGE_LIMITS.entryBytes` per key) fails `limit`, and an
+     * object's properties are stored sorted, as the player hands them back.
+     *
+     * @since 1.5.25
+     */
+    readonly sessionStorage: Map<string, Json>;
     /** What `plugin.app.system()` reports. */
     systemInfo: WireSystemInfo;
     /**
@@ -1594,6 +1608,15 @@ export declare function startPlugin(activate: (plugin: Plugin) => unknown, optio
     host?: TestHost;
     /** Use an existing directory as `plugin.dataDirectory` (to test a restart). */
     dataDirectory?: string;
+    /**
+     * Start with these `plugin.storage.session` values (to test a restart
+     * within one player session): pass the previous run's
+     * `host.sessionStorage`. They are copied into the new host's
+     * {@link TestHost.sessionStorage}.
+     *
+     * @since 1.5.25
+     */
+    sessionStorage?: ReadonlyMap<string, Json>;
     /**
      * The interface language to play ({@link TestHost.locale}): the plugin's
      * `locales/<locale>.po` (or `.json`) in `directory` is loaded and its

package/dist/plugin/testing.js

@@ -69,7 +69,7 @@ import { localSocketPath } from "./local.js";
 import { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "../commands.js";
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
 import { OSD_LIMITS } from "./osd.js";
-import { SECRET_LIMITS } from "./services.js";
+import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.js";
 import { BINDING_INPUTS } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
@@ -93,6 +93,8 @@ export { MESSAGE_LIMIT };
 export { OSD_LIMITS };
 /** The player's limits on stored secrets. */
 export { SECRET_LIMITS };
+/** The player's limits on `plugin.storage.session`. */
+export { SESSION_STORAGE_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -131,6 +133,34 @@ export { LIST_SEPARATORS };
  * ```
  */
 export { LOCALES };
+/** A `plugin.storage.session` key, checked as the player does. */
+function sessionKey(key) {
+    if (typeof key !== "string" ||
+        !key ||
+        key.includes("\0") ||
+        Buffer.byteLength(key) > SESSION_STORAGE_LIMITS.keyBytes)
+        throw new HostError("invalid", "session storage keys are 1–1024 bytes of text without NUL");
+    return key;
+}
+/** Code point (UTF-8 byte) order, as the player sorts session keys. */
+const byCodePoint = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+/**
+ * A JSON value as the player hands it back: the player does not keep the
+ * order of object properties, it sorts them.
+ */
+function sortedJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortedJson);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.keys(value)
+            .sort(byCodePoint)
+            .map((key) => [key, sortedJson(value[key])]));
+    return value;
+}
+/** What one session entry counts towards the player's quota. */
+const sessionCost = (key, value) => Buffer.byteLength(key) +
+    Buffer.byteLength(JSON.stringify(value)) +
+    SESSION_STORAGE_LIMITS.entryBytes;
 const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
 const tick = () => new Promise((resolve) => setImmediate(resolve));
 function initialSource() {
@@ -1156,6 +1186,18 @@ export class TestHost {
      * new name fails `limit` once 256 names are stored.
      */
     secrets = new Map();
+    /**
+     * `plugin.storage.session`: key → value, as the player keeps them. Preset
+     * entries to simulate values an earlier run of the plugin stored in the
+     * same player session, or pass `startPlugin(..., { sessionStorage })`.
+     * Like the player, a key is 1–1024 bytes, a `set` that would make the
+     * entries larger than 1 MiB (keys, values as compact JSON and
+     * `SESSION_STORAGE_LIMITS.entryBytes` per key) fails `limit`, and an
+     * object's properties are stored sorted, as the player hands them back.
+     *
+     * @since 1.5.25
+     */
+    sessionStorage = new Map();
     /** What `plugin.app.system()` reports. */
     systemInfo = {
         os: "macos",
@@ -1622,6 +1664,11 @@ export class TestHost {
      */
     async request(method, params = {}) {
         const record = (params ?? {});
+        // The plugin runner refuses a request over the message limit before
+        // sending it (runtime/runner.ts): the player never sees it.
+        const line = JSON.stringify({ id: this.calls.length + 1, method, params });
+        if (Buffer.byteLength(line, "utf8") + 1 > MESSAGE_LIMIT)
+            throw new HostError("limit", `${method}: request exceeds the player's 1 MiB message limit`);
         this.calls.push({ method, params: record });
         this.#inFlight++;
         try {
@@ -2709,6 +2756,27 @@ export class TestHost {
             this.secrets.set(name, String(p.value));
         },
         "secrets.delete": (p) => void this.secrets.delete(String(p.name)),
+        // As the player (host/src/session_storage.rs).
+        "storage.session.get": (p) => {
+            const key = sessionKey(p.key);
+            return this.sessionStorage.has(key)
+                ? { value: structuredClone(this.sessionStorage.get(key)) }
+                : {};
+        },
+        "storage.session.set": (p) => {
+            const key = sessionKey(p.key);
+            if (!("value" in p))
+                throw new HostError("invalid", "set needs a JSON value");
+            let total = sessionCost(key, p.value);
+            for (const [other, value] of this.sessionStorage)
+                if (other !== key)
+                    total += sessionCost(other, value);
+            if (total > SESSION_STORAGE_LIMITS.bytes)
+                throw new HostError("limit", `session storage holds at most ${SESSION_STORAGE_LIMITS.bytes} bytes per plugin (keys, JSON values and ${SESSION_STORAGE_LIMITS.entryBytes} per key); this value would make ${total}`);
+            this.sessionStorage.set(key, sortedJson(p.value));
+        },
+        "storage.session.delete": (p) => void this.sessionStorage.delete(sessionKey(p.key)),
+        "storage.session.keys": () => [...this.sessionStorage.keys()].sort(byCodePoint),
         "app.system": () => structuredClone(this.systemInfo),
         "clipboard.readText": () => this.clipboard.text,
         "clipboard.writeText": (p) => {
@@ -3741,6 +3809,8 @@ export async function startPlugin(activate, options = {}) {
     host.manifestId = manifest.id;
     host.loadCatalog(directory);
     const data = options.dataDirectory ?? host.dataDirectory;
+    for (const [key, value] of options.sessionStorage ?? [])
+        host.sessionStorage.set(key, sortedJson(value));
     mkdirSync(data, { recursive: true });
     const instance = await createPlugin(host, manifest, directory, data, host.app);
     await activate(instance.plugin);

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
@@ -5232,6 +5233,83 @@ export interface Storage {
         validate?: (value: unknown) => value is T;
         debounceMs?: number;
     }): JsonStore<T>;
+    /**
+     * Values the player keeps in its memory for this plugin until the player
+     * quits: they survive a restart of the plugin's process (reload, upgrade,
+     * crash, failed start) but not the player. See {@link SessionStorage}.
+     *
+     * @since 1.5.25
+     */
+    readonly session: SessionStorage;
+}
+/**
+ * `plugin.storage.session`: JSON values that live as long as the **player**,
+ * not as long as the plugin's process (like `chrome.storage.session`). No
+ * capability; needs player 0.5.5 (older players reject the calls with
+ * `unsupported`).
+ *
+ * `activate` can run more than once in one player session: the player stops
+ * and starts a plugin's process again when the plugin is reloaded (also a
+ * development load with `--plugin`) or upgraded, and after a crash or a
+ * failed start. A later player may also restart plugins that share a
+ * process, or stop an idle plugin and start it on its next use. Variables do
+ * not survive that; keep state that must survive a restart here (or in
+ * {@link Storage.json | storage.json} when it must also survive the player
+ * quitting).
+ *
+ * | | Values |
+ * | --- | --- |
+ * | The plugin's process restarts: reload, upgrade, crash | kept |
+ * | The plugin failed to start or failed, and starts again | kept |
+ * | The user disables the plugin, or uninstalls it | cleared |
+ * | The player quits | cleared |
+ *
+ * - **Per plugin.** A plugin sees only its own keys. Like
+ *   {@link Plugin.dataDirectory | dataDirectory}, the values belong to the
+ *   installation: a development load (`--plugin`) has its own.
+ * - **JSON.** `set` stores what `JSON.stringify(value)` writes, and `get`
+ *   returns that, parsed: `undefined` object properties are dropped, a `Date`
+ *   comes back as a string, `NaN` as `null`. **The order of an object's
+ *   properties is not kept**: they may come back in another order. A value
+ *   `JSON.stringify` cannot write (`undefined`, a function, a cycle, a
+ *   `BigInt`) or a string with a lone surrogate (`"\uD800"`) fails with
+ *   `invalid`. The value is not checked when it comes back: after an upgrade
+ *   an older version's value may be read, so check its shape when it matters.
+ * - **Bounded.** Keys are 1–1024 bytes of text. A plugin holds at most 1 MiB,
+ *   counting every key, its value as compact JSON and 128 bytes per key
+ *   ({@link "@vestra-player/sdk/testing"!SESSION_STORAGE_LIMITS | SESSION_STORAGE_LIMITS}); a
+ *   `set` beyond it fails with `limit` and changes nothing. One `set` is
+ *   also one message to the player, at most 1 MiB with its key, so a single
+ *   value is a little smaller than that; a larger one fails with `limit`.
+ *   Split large state over several keys.
+ * - **Each call is one request.** A `set` is kept once its promise
+ *   resolves, so a crash right after loses nothing; there is no debounce.
+ *   Calls answer in order.
+ *
+ * @example
+ * ```ts
+ * // A queue the plugin is working through: after a reload or a crash it
+ * // goes on where it stopped, after the player quits it starts afresh.
+ * const pending = (await plugin.storage.session.get<string[]>("queue")) ?? [];
+ * pending.push("https://example.com/a.mkv");
+ * await plugin.storage.session.set("queue", pending);
+ * ```
+ *
+ * @since 1.5.25
+ */
+export interface SessionStorage {
+    /** The value stored under `key`, or `undefined` when there is none. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Store or replace `value` under `key`. `invalid` for a bad key or a value
+     * that is not JSON, `limit` when the plugin's values would be over 1 MiB
+     * or the request over the 1 MiB message limit.
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /** Remove a key; removing a missing one is fine. */
+    delete(key: string): Promise<void>;
+    /** The keys stored, in code point order. */
+    keys(): Promise<string[]>;
 }
 /**
  * `plugin.system`: files and links, executed by the player. No capability.

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;
+        },
+    };
+}

package/dist/wire.d.ts

@@ -488,6 +488,18 @@ export declare function createWire(transport: Transport): {
         set: (name: string, value: string) => Promise<void>;
         delete: (name: string) => Promise<void>;
     };
+    /**
+     * JSON values the player keeps per plugin until it quits (SDK 1.5.25,
+     * player 0.5.5). `get` answers `{}` for a missing key.
+     */
+    storageSession: {
+        get: (key: string) => Promise<{
+            value?: Json;
+        }>;
+        set: (key: string, value: Json) => Promise<void>;
+        delete: (key: string) => Promise<void>;
+        keys: () => Promise<string[]>;
+    };
     app: {
         system: () => Promise<WireSystemInfo>;
     };

package/dist/wire.js

@@ -182,6 +182,16 @@ export function createWire(transport) {
             set: (name, value) => transport.request("secrets.set", { name, value }),
             delete: (name) => transport.request("secrets.delete", { name }),
         },
+        /**
+         * JSON values the player keeps per plugin until it quits (SDK 1.5.25,
+         * player 0.5.5). `get` answers `{}` for a missing key.
+         */
+        storageSession: {
+            get: (key) => transport.request("storage.session.get", { key }),
+            set: (key, value) => transport.request("storage.session.set", { key, value }),
+            delete: (key) => transport.request("storage.session.delete", { key }),
+            keys: () => transport.request("storage.session.keys"),
+        },
         app: {
             system: () => transport.request("app.system"),
         },