@vestra-player/sdk 1.5.33 → 1.5.35

package/dist/plugin/testing.d.ts

@@ -8,13 +8,14 @@ import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.ts";
 import type { CapabilityInfo } from "../capabilities.ts";
 import { OSD_LIMITS } from "./osd.ts";
 import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.ts";
+import { SUBTITLE_LIMITS } from "./subtitles.ts";
 import { BINDING_INPUTS } from "./bindings.ts";
 import { THEME_PALETTES } from "../palettes.ts";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
-import type { RenderSettings, ViewSettings } from "./types.ts";
+import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
 import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
 import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
@@ -38,6 +39,8 @@ export { OSD_LIMITS };
 export { SECRET_LIMITS };
 /** The player's limits on `plugin.storage.session`. */
 export { SESSION_STORAGE_LIMITS };
+/** The player's limits on loaded subtitle files, which the test host enforces as well. */
+export { SUBTITLE_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -466,7 +469,7 @@ export interface MarkdownWire {
  *   {@link TestHost.app}, {@link TestHost.systemInfo},
  *   {@link TestHost.chapters}, {@link TestHost.audioDevices},
  *   {@link TestHost.secrets}, {@link TestHost.clipboard},
- *   {@link TestHost.tools}.
+ *   {@link TestHost.tools}, {@link TestHost.rendering}.
  * - **Assert** on records: {@link TestHost.osd}, {@link TestHost.calls},
  *   {@link TestHost.sent}, {@link TestHost.conflicts},
  *   {@link TestHost.layout}, {@link TestHost.menus}, and many more.
@@ -1270,7 +1273,10 @@ export declare class TestHost implements Transport {
         owner: string | null;
         /** The values the player holds. */
         values: RenderSettings;
-        /** `true`: GPU rendering; `false`: software rendering (`unsupported`). */
+        /**
+         * `true`: GPU rendering; `false`: software rendering (`unsupported`).
+         * `plugin.app.system()` reports it as `rendering`.
+         */
         gpu: boolean;
     };
     /**
@@ -1300,7 +1306,8 @@ export declare class TestHost implements Transport {
     /**
      * What the player pushes when mpv cannot compile a shader (code `failed`)
      * or switches to software rendering (`unsupported`, which also sets
-     * `videoRender.gpu` to false). Pushed only when this plugin is the owner.
+     * `videoRender.gpu` to false and `rendering.reason` to `window-fallback`
+     * with `message`). Pushed only when this plugin is the owner.
      *
      * @example Make a shader fail to compile
      * The plugin's render options report `failed`, as when mpv rejects a
@@ -1385,6 +1392,13 @@ export declare class TestHost implements Transport {
         bytes: Buffer[];
         /** The announced total size in bytes. */
         expected: number;
+        /**
+         * The source generation it was begun for; like the player, a new
+         * source drops the uploads of the old one.
+         *
+         * @since 1.5.34
+         */
+        generation?: number;
     }>;
     /** Snapshots taken with `media.capture`, by snapshot id. Wire-level. */
     readonly snapshots: Map<number, Json>;
@@ -1595,8 +1609,13 @@ export declare class TestHost implements Transport {
      * @since 1.5.25
      */
     readonly sessionStorage: Map<string, Json>;
-    /** What `plugin.app.system()` reports. */
-    systemInfo: WireSystemInfo;
+    /**
+     * What `plugin.app.system()` reports. Its `rendering` follows
+     * {@link TestHost.videoRender | videoRender.gpu} (`"gpu"` or
+     * `"software"`), so one switch covers the render options and the fact;
+     * its `renderingReason` is {@link TestHost.rendering | rendering.reason}.
+     */
+    systemInfo: Omit<WireSystemInfo, "rendering" | "renderingReason">;
     /**
      * What `plugin.app` reports. Set it before {@link startPlugin}: the plugin
      * receives it once at start-up.
@@ -1616,6 +1635,74 @@ export declare class TestHost implements Transport {
             slint: string;
         };
     };
+    /**
+     * The player's rendering choice behind `plugin.rendering` (player
+     * 0.5.13). The mode drawing now is {@link TestHost.videoRender |
+     * videoRender.gpu}, as for `plugin.app.system()`; the rest is preset here
+     * and changed by the plugin's calls, as the player would:
+     *
+     * - `setPreference` saves `preference` and never changes the mode. It
+     *   refuses `"gpu"` while `gpu.available` is false: with `unsupported`
+     *   when `gpu.reason.code` is `no-gpu-backend` or `headless`, otherwise
+     *   with `unavailable`, the reason's message in both cases.
+     * - The next start uses `"software"` for the `"software"` choice, else
+     *   software with `gpu.reason` while the GPU is not available, else the
+     *   GPU (code `preference` for a `"gpu"` choice, `default` for
+     *   `"auto"`). `restartPending` compares that with `startedWith`.
+     * - `restartPlayer` counts in `restarts` and leaves the plugin running
+     *   (call `stop()` yourself); a second one rejects with `busy`, as a
+     *   restart is then under way.
+     *
+     * Inject other refusals (`failed` for an unwritable settings file or a
+     * new process that could not start) with `host.handle("rendering.setPreference", …)`
+     * or `host.handle("rendering.restart", …)`. The defaults are a macOS
+     * player on the GPU: `"auto"`, available, started on the GPU.
+     *
+     * @example Test a GPU switch on a system without a GPU renderer
+     * The plugin's GPU menu item is greyed out with the player's reason when
+     * the GPU cannot be chosen. The host is preset before the plugin starts,
+     * because the plugin reads the state while activating; software
+     * rendering is `videoRender.gpu = false`, and `gpu` says why the GPU
+     * cannot be chosen.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+     * import activate from "../main.ts";
+     *
+     * const host = new TestHost();
+     * host.videoRender.gpu = false; // software draws now (Windows)
+     * host.rendering.startedWith = "software";
+     * host.rendering.reason = { code: "no-gpu-backend", message: "No GPU renderer on Windows" };
+     * host.rendering.gpu = { available: false, reason: host.rendering.reason };
+     * const { stop } = await startPlugin(activate, {
+     *   directory: new URL("..", import.meta.url),
+     *   host,
+     * });
+     * const item = host.command("gpu-rendering");
+     * assert.equal(item.state.enabled, false);
+     * assert.equal(item.state.reason, "No GPU renderer on Windows");
+     * await stop();
+     * ```
+     *
+     * @since 1.5.35
+     */
+    readonly rendering: {
+        /** Why the mode drawing now is what it is (`RenderingState.reason`, `SystemInfo.renderingReason`). */
+        reason: RenderingReason;
+        /** The saved choice: `"auto"`, `"gpu"` or `"software"`. */
+        preference: RenderingPreference;
+        /** The mode this run started with; `restartPending` compares the next start's mode with it. */
+        startedWith: RenderingMode;
+        /** Whether the plugin may choose `"gpu"`, and why not (`null` while available). */
+        gpu: {
+            /** `false`: `setPreference("gpu")` is refused. */
+            available: boolean;
+            /** Why the GPU cannot be chosen; `null` while it can. */
+            reason: RenderingReason | null;
+        };
+        /** Accepted `restartPlayer` calls. */
+        restarts: number;
+    };
     /** What `player.chapters()` lists while media is ready. */
     chapters: {
         /** The chapter title, `null` without one. */

package/dist/plugin/testing.js

@@ -77,6 +77,7 @@ import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, BUILTIN_SUBMENUS
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
 import { OSD_LIMITS } from "./osd.js";
 import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.js";
+import { SUBTITLE_LIMITS } from "./subtitles.js";
 import { BINDING_INPUTS } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
@@ -104,6 +105,8 @@ export { OSD_LIMITS };
 export { SECRET_LIMITS };
 /** The player's limits on `plugin.storage.session`. */
 export { SESSION_STORAGE_LIMITS };
+/** The player's limits on loaded subtitle files, which the test host enforces as well. */
+export { SUBTITLE_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -265,7 +268,7 @@ const MAX_SIDEBAR_TABS = 8;
  *   {@link TestHost.app}, {@link TestHost.systemInfo},
  *   {@link TestHost.chapters}, {@link TestHost.audioDevices},
  *   {@link TestHost.secrets}, {@link TestHost.clipboard},
- *   {@link TestHost.tools}.
+ *   {@link TestHost.tools}, {@link TestHost.rendering}.
  * - **Assert** on records: {@link TestHost.osd}, {@link TestHost.calls},
  *   {@link TestHost.sent}, {@link TestHost.conflicts},
  *   {@link TestHost.layout}, {@link TestHost.menus}, and many more.
@@ -1264,7 +1267,8 @@ export class TestHost {
     /**
      * What the player pushes when mpv cannot compile a shader (code `failed`)
      * or switches to software rendering (`unsupported`, which also sets
-     * `videoRender.gpu` to false). Pushed only when this plugin is the owner.
+     * `videoRender.gpu` to false and `rendering.reason` to `window-fallback`
+     * with `message`). Pushed only when this plugin is the owner.
      *
      * @example Make a shader fail to compile
      * The plugin's render options report `failed`, as when mpv rejects a
@@ -1287,8 +1291,10 @@ export class TestHost {
      * @since 1.0.0
      */
     failVideoRender(code, message) {
-        if (code === "unsupported")
+        if (code === "unsupported") {
             this.videoRender.gpu = false;
+            this.rendering.reason = { code: "window-fallback", message };
+        }
         if (this.videoRender.owner === this.manifestId)
             this.emit("video.render.status", {
                 state: "failed",
@@ -1521,7 +1527,12 @@ export class TestHost {
      * @since 1.5.25
      */
     sessionStorage = new Map();
-    /** What `plugin.app.system()` reports. */
+    /**
+     * What `plugin.app.system()` reports. Its `rendering` follows
+     * {@link TestHost.videoRender | videoRender.gpu} (`"gpu"` or
+     * `"software"`), so one switch covers the render options and the fact;
+     * its `renderingReason` is {@link TestHost.rendering | rendering.reason}.
+     */
     systemInfo = {
         os: "macos",
         name: "macOS",
@@ -1553,6 +1564,64 @@ export class TestHost {
             slint: "1.18.1",
         },
     };
+    /**
+     * The player's rendering choice behind `plugin.rendering` (player
+     * 0.5.13). The mode drawing now is {@link TestHost.videoRender |
+     * videoRender.gpu}, as for `plugin.app.system()`; the rest is preset here
+     * and changed by the plugin's calls, as the player would:
+     *
+     * - `setPreference` saves `preference` and never changes the mode. It
+     *   refuses `"gpu"` while `gpu.available` is false: with `unsupported`
+     *   when `gpu.reason.code` is `no-gpu-backend` or `headless`, otherwise
+     *   with `unavailable`, the reason's message in both cases.
+     * - The next start uses `"software"` for the `"software"` choice, else
+     *   software with `gpu.reason` while the GPU is not available, else the
+     *   GPU (code `preference` for a `"gpu"` choice, `default` for
+     *   `"auto"`). `restartPending` compares that with `startedWith`.
+     * - `restartPlayer` counts in `restarts` and leaves the plugin running
+     *   (call `stop()` yourself); a second one rejects with `busy`, as a
+     *   restart is then under way.
+     *
+     * Inject other refusals (`failed` for an unwritable settings file or a
+     * new process that could not start) with `host.handle("rendering.setPreference", …)`
+     * or `host.handle("rendering.restart", …)`. The defaults are a macOS
+     * player on the GPU: `"auto"`, available, started on the GPU.
+     *
+     * @example Test a GPU switch on a system without a GPU renderer
+     * The plugin's GPU menu item is greyed out with the player's reason when
+     * the GPU cannot be chosen. The host is preset before the plugin starts,
+     * because the plugin reads the state while activating; software
+     * rendering is `videoRender.gpu = false`, and `gpu` says why the GPU
+     * cannot be chosen.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+     * import activate from "../main.ts";
+     *
+     * const host = new TestHost();
+     * host.videoRender.gpu = false; // software draws now (Windows)
+     * host.rendering.startedWith = "software";
+     * host.rendering.reason = { code: "no-gpu-backend", message: "No GPU renderer on Windows" };
+     * host.rendering.gpu = { available: false, reason: host.rendering.reason };
+     * const { stop } = await startPlugin(activate, {
+     *   directory: new URL("..", import.meta.url),
+     *   host,
+     * });
+     * const item = host.command("gpu-rendering");
+     * assert.equal(item.state.enabled, false);
+     * assert.equal(item.state.reason, "No GPU renderer on Windows");
+     * await stop();
+     * ```
+     *
+     * @since 1.5.35
+     */
+    rendering = {
+        reason: { code: "default", message: "nothing rules GPU rendering out" },
+        preference: "auto",
+        startedWith: "gpu",
+        gpu: { available: true, reason: null },
+        restarts: 0,
+    };
     /** What `player.chapters()` lists while media is ready. */
     chapters = [];
     #overrides = new Map();
@@ -3135,17 +3204,102 @@ export class TestHost {
             !["ready", "ended"].includes(this.source.phase))
             throw new HostError("unavailable", "audio tracks need ready media");
     }
-    #subtitleChange(expected) {
+    /** `stale` unless `expected` is the current subtitle stamp. */
+    #subtitleExpected(expected) {
         const stamp = this.subtitles.selection.stamp;
         const want = expected;
         if (want.generation !== stamp.generation ||
             want.revision !== stamp.revision)
             throw new HostError("stale", "subtitle selection changed");
+    }
+    /**
+     * The resources this plugin loaded into the current source (resource id →
+     * bytes), removed ones included: like the player, a removed track frees
+     * its place among the live tracks but not among the loads.
+     */
+    #subtitleResources = { generation: -1, bytes: new Map() };
+    #loadedSubtitles() {
+        const generation = this.source.stamp.generation;
+        if (this.#subtitleResources.generation !== generation)
+            this.#subtitleResources = { generation, bytes: new Map() };
+        return this.#subtitleResources.bytes;
+    }
+    /**
+     * The player's `SUBTITLE_LIMITS` for a new resource (`busy`, as the
+     * player reports them). External tracks in `subtitles.tracks` that this
+     * plugin did not load count as other plugins'. `totalBytes` is not
+     * modelled: one plugin's 4 files of at most 2 MiB stay below it, and the
+     * bytes of other plugins' tracks are unknown.
+     */
+    #subtitleRoom(resourceId) {
+        const loaded = this.#loadedSubtitles();
+        if (loaded.has(resourceId))
+            return;
+        const external = this.subtitles.tracks.filter((t) => t.target.kind === "external");
+        const own = external.filter((t) => t.target.kind === "external" && loaded.has(t.target.resourceId));
+        const others = external.length - own.length;
+        if (loaded.size >= SUBTITLE_LIMITS.loadsPerPlugin ||
+            loaded.size + others >= SUBTITLE_LIMITS.loads ||
+            own.length >= SUBTITLE_LIMITS.tracksPerPlugin ||
+            external.length >= SUBTITLE_LIMITS.tracks)
+            throw new HostError("busy", "subtitle resource or counter limit exceeded");
+    }
+    #subtitleChange(expected) {
+        this.#subtitleExpected(expected);
+        const stamp = this.subtitles.selection.stamp;
         this.subtitles.selection.stamp = {
             generation: this.source.stamp.generation,
             revision: stamp.revision + 1,
         };
     }
+    /** `rendering.state` from {@link TestHost.rendering} and `videoRender.gpu`. */
+    #renderingState() {
+        const { reason, preference, startedWith, gpu } = this.rendering;
+        // The player's order (render_mode.rs decide): no windows or no GPU
+        // renderer first, then the preference `software`, then what keeps GPU
+        // rendering off (denylist, crash), else GPU with the reason `default`
+        // (also when the preference is `gpu`).
+        const system = !gpu.available &&
+            (gpu.reason?.code === "headless" ||
+                gpu.reason?.code === "no-gpu-backend");
+        const next = system
+            ? { mode: "software", reason: gpu.reason }
+            : preference === "software"
+                ? {
+                    mode: "software",
+                    reason: {
+                        code: "preference",
+                        message: "chosen in the player's settings",
+                    },
+                }
+                : !gpu.available
+                    ? {
+                        mode: "software",
+                        reason: gpu.reason ?? {
+                            code: "default",
+                            message: "nothing rules GPU rendering out",
+                        },
+                    }
+                    : {
+                        mode: "gpu",
+                        reason: {
+                            code: "default",
+                            message: "nothing rules GPU rendering out",
+                        },
+                    };
+        return {
+            mode: this.videoRender.gpu ? "gpu" : "software",
+            reason: { ...reason },
+            preference,
+            nextMode: next.mode,
+            nextReason: { ...next.reason },
+            restartPending: next.mode !== startedWith,
+            gpu: {
+                available: gpu.available,
+                reason: gpu.available || !gpu.reason ? null : { ...gpu.reason },
+            },
+        };
+    }
     #defaults = {
         "events.subscribe": (p) => void this.subscriptions.add(String(p.event)),
         "events.unsubscribe": (p) => void this.subscriptions.delete(String(p.event)),
@@ -3459,7 +3613,33 @@ export class TestHost {
         },
         "storage.session.delete": (p) => void this.sessionStorage.delete(sessionKey(p.key)),
         "storage.session.keys": () => [...this.sessionStorage.keys()].sort(byCodePoint),
-        "app.system": () => structuredClone(this.systemInfo),
+        "app.system": () => ({
+            ...structuredClone(this.systemInfo),
+            rendering: this.videoRender.gpu ? "gpu" : "software",
+            renderingReason: { ...this.rendering.reason },
+        }),
+        // As the player 0.5.13 (see TestHost.rendering for the model).
+        "rendering.state": () => this.#renderingState(),
+        "rendering.setPreference": (p) => {
+            const preference = p.preference;
+            if (preference !== "auto" &&
+                preference !== "gpu" &&
+                preference !== "software")
+                throw new HostError("invalid", 'preference must be "auto", "gpu" or "software"');
+            const { available, reason } = this.rendering.gpu;
+            if (preference === "gpu" && !available)
+                throw new HostError(reason?.code === "no-gpu-backend" || reason?.code === "headless"
+                    ? "unsupported"
+                    : "unavailable", reason?.message ?? "GPU rendering cannot be chosen");
+            this.rendering.preference = preference;
+            return this.#renderingState();
+        },
+        "rendering.restart": () => {
+            if (this.rendering.restarts > 0)
+                throw new HostError("busy", "a restart is already under way");
+            this.rendering.restarts++;
+            return null;
+        },
         "clipboard.readText": () => this.clipboard.text,
         "clipboard.writeText": (p) => {
             if (typeof p.text !== "string")
@@ -4143,9 +4323,24 @@ export class TestHost {
         "subtitles.upload.begin": (p) => {
             if (p.generation !== this.source.stamp.generation)
                 throw new HostError("stale", "source generation changed");
+            const expectedBytes = Number(p.expectedBytes);
+            if (!Number.isSafeInteger(expectedBytes) ||
+                expectedBytes < 1 ||
+                expectedBytes > SUBTITLE_LIMITS.fileBytes)
+                throw new HostError("invalid", `a subtitle file has 1..${SUBTITLE_LIMITS.fileBytes} bytes`);
+            // Like the player: a new source drops the old one's uploads. A commit
+            // the player refused leaves its upload for `subtitles.upload.discard`,
+            // which the SDK sends after any failed load.
+            for (const [id, upload] of this.uploads)
+                if (upload.generation !== undefined &&
+                    upload.generation !== this.source.stamp.generation)
+                    this.uploads.delete(id);
+            if (this.uploads.size >= SUBTITLE_LIMITS.uploadsPerPlugin)
+                throw new HostError("busy", "upload memory, owner or active-token limit reached");
             this.uploads.set(Number(p.uploadId), {
                 bytes: [],
-                expected: Number(p.expectedBytes),
+                expected: expectedBytes,
+                generation: this.source.stamp.generation,
             });
             return {
                 generation: p.generation,
@@ -4163,9 +4358,8 @@ export class TestHost {
         },
         "subtitles.upload.discard": (p) => void this.uploads.delete(Number(p.uploadId)),
         "subtitles.commit": (p) => {
-            const upload = this.uploads.get(Number(p.uploadId));
-            if (!upload)
-                throw new HostError("missing", "upload");
+            // The player's order: the request's own fields, then `stale`, then
+            // the upload and its content, then the limits.
             const format = p.format === "ass" ? "ass" : "srt";
             const select = p.select === "none"
                 ? "none"
@@ -4179,12 +4373,18 @@ export class TestHost {
                     : null;
             if (title !== null && ([...title].length < 1 || [...title].length > 200))
                 throw new HostError("invalid", "subtitle title needs 1..200 characters");
+            this.#subtitleExpected(p.expected);
+            const upload = this.uploads.get(Number(p.uploadId));
+            if (!upload)
+                throw new HostError("missing", "upload");
             const bytes = Buffer.concat(upload.bytes);
             if (format === "ass" &&
                 !(/\[Script Info\]/i.test(bytes.toString()) &&
                     /\[Events\]/i.test(bytes.toString())))
                 throw new HostError("invalid", "ASS requires [Script Info] and [Events] sections");
+            this.#subtitleRoom(String(p.resourceId));
             this.#subtitleChange(p.expected);
+            this.#loadedSubtitles().set(String(p.resourceId), bytes.length);
             const target = {
                 kind: "external",
                 owner: 1,