@vestra-player/sdk 1.5.38 → 1.5.40

package/dist/plugin/testing.js

@@ -64,12 +64,12 @@
  * @packageDocumentation
  * @module @vestra-player/sdk/testing
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, openSync, readFileSync, readSync, closeSync, realpathSync, } from "node:fs";
 import { mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { createServer } from "node:net";
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
-import { extname, isAbsolute, join } from "node:path";
+import { extname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HostError } from "../wire.js";
 import { localSocketPath } from "./local.js";
@@ -82,9 +82,12 @@ import { BINDING_INPUTS } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
 import { validStep } from "./player.js";
-import { nodeProblem } from "../processing.js";
+import { nodeProblem, VIDEO_PROCESSING_LIMITS } from "../processing.js";
+import { shaderIdProblem, shaderListProblem } from "./shaders.js";
 import { RENDER_DEFAULTS, renderProblem, VIEW_DEFAULTS, viewProblem, } from "./view.js";
 import { createPlugin } from "./index.js";
+import { evaluate } from "./when.js";
+import { WAKE_EVENTS } from "./runtime.js";
 import { THEMES } from "./appearance.js";
 import { Catalog, format as formatTemplate, HOST_GROUPS, HOST_ZH_HANS, LOCALES, fitColumns, isTextValue, LIST_SEPARATORS, loadPackageCatalog, menuKeys, renderTemplateArgs, renderText, resolveTexts, TEXT_LIMITS, textKey, textProblem, } from "../i18n.js";
 /** Throw one of these from `host.handle(...)` to simulate a definite refusal. */
@@ -107,6 +110,8 @@ export { SECRET_LIMITS };
 export { SESSION_STORAGE_LIMITS };
 /** The player's limits on loaded subtitle files, which the test host enforces as well. */
 export { SUBTITLE_LIMITS };
+/** The player's bounds on convolution, lut3d and shader-channel requests, which the test host enforces as well. */
+export { VIDEO_PROCESSING_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -188,6 +193,70 @@ const sessionCost = (key, value) => Buffer.byteLength(key) +
     SESSION_STORAGE_LIMITS.entryBytes;
 const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
 const tick = () => new Promise((resolve) => setImmediate(resolve));
+/**
+ * The player's `playback/plugin_files.rs`: a file the plugin names for its
+ * video processing is an absolute path inside one of `roots` after
+ * following links, a regular file of at most `max` bytes. Returns the real
+ * path or throws the player's error.
+ */
+function ownFile(path, roots, what, max) {
+    if (!isAbsolute(path))
+        throw new HostError("invalid", `${what} path must be absolute: ${path}`);
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch {
+        throw new HostError("missing", `${what} not found: ${path}`);
+    }
+    const inside = roots.some((root) => {
+        let base;
+        try {
+            base = realpathSync(root);
+        }
+        catch {
+            return false;
+        }
+        const rel = relative(base, real);
+        return rel === "" || (!/^\.\.([\\/]|$)/.test(rel) && !isAbsolute(rel));
+    });
+    if (!inside)
+        throw new HostError("invalid", `${what} must be in the plugin's package or data directory: ${path}`);
+    const stat = statSync(real);
+    if (!stat.isFile())
+        throw new HostError("invalid", `${what} is not a file: ${path}`);
+    if (stat.size > max)
+        throw new HostError("invalid", `${what} is larger than ${max / 1024 / 1024} MiB: ${path}`);
+    return real;
+}
+/** The `LUT_3D_SIZE` check of `plugin_files::lut` on the first 64 KiB. */
+function cubeProblem(file) {
+    const buffer = Buffer.alloc(64 * 1024);
+    const fd = openSync(file, "r");
+    let read;
+    try {
+        read = readSync(fd, buffer, 0, buffer.length, 0);
+    }
+    finally {
+        closeSync(fd);
+    }
+    for (const line of buffer.subarray(0, read).toString("utf8").split("\n")) {
+        const [word, value] = line.trim().split(/\s+/);
+        if (word === "LUT_3D_SIZE") {
+            const size = Number(value);
+            return Number.isInteger(size) &&
+                size >= 2 &&
+                size <= VIDEO_PROCESSING_LIMITS.lutSize
+                ? null
+                : `LUT_3D_SIZE must be 2 to ${VIDEO_PROCESSING_LIMITS.lutSize}`;
+        }
+        if (word === "LUT_1D_SIZE")
+            return "a 1D LUT; lut3d needs LUT_3D_SIZE";
+        if (word !== undefined && word !== "" && Number.isFinite(Number(word)))
+            break;
+    }
+    return "no LUT_3D_SIZE line before the data";
+}
 function initialSource() {
     return {
         kind: "media",
@@ -343,6 +412,16 @@ export class TestHost {
      * @since 1.5.38
      */
     listening = new Set();
+    /**
+     * Why the plugin listens to each event of {@link TestHost.listening}:
+     * every listener and every binding that reads its state, as the
+     * player's log says them (`a listener added at main.ts:12`,
+     * `command "Save" enabled is a function that reads plugin.player.state
+     * (main.ts:40) — use plugin.when`), in the order they came.
+     *
+     * @since 1.5.40
+     */
+    listeningWhy = new Map();
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with
@@ -1311,6 +1390,78 @@ export class TestHost {
                 state: "failed",
                 error: { code, message },
             });
+        // The player tells every shader handle too (`failVideoShaders`).
+        // and, like the player, removes their lists.
+        if (code === "unsupported") {
+            for (const [id, paths] of this.videoShaders.handles)
+                if (paths.length > 0)
+                    this.emit("video.shaders.status", {
+                        id,
+                        state: "failed",
+                        error: { code, message },
+                    });
+            this.videoShaders.handles.clear();
+        }
+    }
+    /**
+     * The shader channel (`plugin.video.shaders(id)`, SDK 1.5.39): the lists
+     * the player holds for this plugin's handles by id (the real paths, after
+     * following links), and how many shaders other plugins hold, which count
+     * against {@link VIDEO_PROCESSING_LIMITS}`.shaders` (`limit`). Files must
+     * be under {@link TestHost.fileRoots}; under software rendering
+     * (`videoRender.gpu = false`) a non-empty list fails with `unsupported`.
+     *
+     * @since 1.5.39
+     */
+    videoShaders = { handles: new Map(), others: 0 };
+    /**
+     * Where the plugin's own files may be: its package directory and its
+     * data directory ({@link startPlugin} sets both when the list is still
+     * empty). `lut3d` files and shader-channel files outside them fail with
+     * `invalid`, as in the player.
+     *
+     * @since 1.5.39
+     */
+    fileRoots = [];
+    /**
+     * What the player pushes to a shader handle when mpv cannot compile a
+     * shader (code `failed`; the player cannot tell whose shader failed, so
+     * every handle with shaders hears it) or the player switches to software
+     * rendering (`unsupported`; use {@link TestHost.failVideoRender}, which
+     * also tells the handles). Pushed only to a handle that holds shaders.
+     *
+     * @capability None.
+     *
+     * @example Make the plugin's shader fail to compile
+     * The plugin's shader handle reports `failed`, as when mpv rejects a
+     * shader. The host pushes the failure only to a handle that holds
+     * shaders, which its accepted `set` made it; the SDK updates the
+     * handle's `status` when the push arrives, so the test settles first.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { join } from "node:path";
+     * import { writeFileSync } from "node:fs";
+     * declare const host: TestHost;
+     * // ---cut---
+     * const file = join(plugin.dataDirectory, "sharpen.glsl");
+     * writeFileSync(file, "//!HOOK MAIN\n");
+     * const shaders = plugin.video.shaders("sharpen");
+     * shaders.set([file]); // the handle now holds a shader
+     * await host.settle();
+     * host.failVideoShaders("sharpen", "shader compile failed: ERROR: 0:3: ...");
+     * await host.settle();
+     * assert.equal(shaders.status.state, "failed");
+     * ```
+     *
+     * @since 1.5.39
+     */
+    failVideoShaders(id, message) {
+        if ((this.videoShaders.handles.get(id)?.length ?? 0) > 0)
+            this.emit("video.shaders.status", {
+                id,
+                state: "failed",
+                error: { code: "failed", message },
+            });
     }
     /**
      * The player's processing (filter) state. Wire-level; may change in minor
@@ -1610,9 +1761,9 @@ export class TestHost {
      * import activate from "../main.ts";
      *
      * const host = new TestHost();
-     * host.videoRender.gpu = false; // software draws now (Windows)
+     * host.videoRender.gpu = false; // software draws now (Linux)
      * host.rendering.startedWith = "software";
-     * host.rendering.reason = { code: "no-gpu-backend", message: "No GPU renderer on Windows" };
+     * host.rendering.reason = { code: "no-gpu-backend", message: "this player has no GPU renderer on Linux yet" };
      * host.rendering.gpu = { available: false, reason: host.rendering.reason };
      * const { stop } = await startPlugin(activate, {
      *   directory: new URL("..", import.meta.url),
@@ -1620,7 +1771,7 @@ export class TestHost {
      * });
      * const item = host.command("gpu-rendering");
      * assert.equal(item.state.enabled, false);
-     * assert.equal(item.state.reason, "No GPU renderer on Windows");
+     * assert.equal(item.state.reason, "this player has no GPU renderer on Linux yet");
      * await stop();
      * ```
      *
@@ -3386,6 +3537,79 @@ export class TestHost {
             },
         };
     }
+    /** A command's state as the player shows it: its conditions evaluated. */
+    #commandShown(sent, when) {
+        if (!when)
+            return sent;
+        const source = this.source;
+        const capabilities = source.capabilities;
+        const facts = {
+            phase: source.phase,
+            paused: source.paused,
+            kind: source.kind === "producer" ? "stream" : "media",
+            can: {
+                pause: capabilities.pause,
+                seek: capabilities.seek,
+                rate: capabilities.rate,
+                restart: capabilities.restart,
+                close: capabilities.close,
+                snapshot: capabilities.snapshotSource,
+                // As the player: the flags merged into the source state.
+                next: source.sequence?.next === true,
+                previous: source.sequence?.previous === true,
+            },
+            fullscreen: this.mainWindow.fullscreen,
+            theme: this.appearance,
+            language: this.language,
+        };
+        const shown = { ...sent };
+        if (when.enabled) {
+            shown.enabled = evaluate(when.enabled, facts);
+            if (shown.enabled && !shown.busy)
+                shown.reason = null;
+        }
+        if (when.checked)
+            shown.checked = evaluate(when.checked, facts);
+        return shown;
+    }
+    /**
+     * Why the player would keep this plugin running while nothing uses it
+     * (lazy activation, player 0.5.21), one line per reason, as the player's
+     * log says it: an event it listens to that is not one the player wakes
+     * it for (with what listens and where it was added), its mounted panel,
+     * its open windows. Empty: the player may stop it while idle and start
+     * it again on its next use. Filter chains, streams, jobs and the like
+     * (which also keep a plugin running) are not listed.
+     *
+     * @capability None.
+     * @since 1.5.40
+     *
+     * @example Check that a plugin can be stopped while idle
+     * The test fails if the plugin keeps running for no reason after it
+     * starts, and names the reason (a command whose `enabled` reads
+     * `plugin.player.state`, say: give it a `plugin.when` condition). The
+     * player stops such a plugin while nothing uses it and starts it again
+     * on its next use, so it costs no process meanwhile.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * assert.deepEqual(host.keepsRunning, []);
+     * ```
+     */
+    get keepsRunning() {
+        const reasons = [];
+        for (const event of this.listening)
+            if (!WAKE_EVENTS.includes(event))
+                for (const why of this.listeningWhy.get(event) ?? ["a listener"])
+                    reasons.push(`listens to ${event}: ${why}`);
+        if (this.panel)
+            reasons.push("a mounted panel");
+        for (const [id, window] of this.windows)
+            if (window.visible)
+                reasons.push(`an open window (${id})`);
+        return reasons;
+    }
     #defaults = {
         "events.subscribe": (p) => {
             const event = String(p.event);
@@ -3394,10 +3618,15 @@ export class TestHost {
                 this.listening.delete(event);
             else
                 this.listening.add(event);
+            if (p.mirror !== true && Array.isArray(p.why))
+                this.listeningWhy.set(event, p.why.map(String));
+            else
+                this.listeningWhy.delete(event);
         },
         "events.unsubscribe": (p) => {
             this.subscriptions.delete(String(p.event));
             this.listening.delete(String(p.event));
+            this.listeningWhy.delete(String(p.event));
         },
         "commands.register": (p) => {
             const id = String(p.id);
@@ -3438,12 +3667,19 @@ export class TestHost {
             for (const segment of [declaration.title, ...(declaration.path ?? [])])
                 this.#declared(segment, "a menu text");
             this.#checkReason(p.state);
+            let sent = p.state;
             this.commands.set(id, {
                 declaration,
                 get display() {
                     return host.#display(declaration.path ?? [], declaration.title, this.state.reason);
                 },
-                state: p.state,
+                ...(p.when ? { when: p.when } : {}),
+                get state() {
+                    return host.#commandShown(sent, this.when);
+                },
+                set state(state) {
+                    sent = state;
+                },
                 revision: Number(p.revision),
                 async run() {
                     if (this.state.busy || !this.state.enabled)
@@ -3465,6 +3701,10 @@ export class TestHost {
             this.#checkReason(p.state);
             command.revision = Number(p.revision);
             command.state = p.state;
+            if (p.when)
+                command.when = p.when;
+            else
+                delete command.when;
             return { revision: command.revision };
         },
         "ui.open": (p) => {
@@ -3985,6 +4225,34 @@ export class TestHost {
                 this.setVideoRenderOwner(null);
             return null;
         },
+        // The player's capability layer and `video_shaders.rs`.
+        "video.shaders.set": (p) => {
+            const idProblem = shaderIdProblem(p.id);
+            if (idProblem)
+                throw new HostError("invalid", idProblem);
+            if (!Array.isArray(p.paths) ||
+                p.paths.some((path) => typeof path !== "string"))
+                throw new HostError("invalid", "paths must be an array of paths");
+            const id = p.id;
+            const list = p.paths;
+            const listProblem = shaderListProblem(list);
+            if (listProblem?.startsWith("at most"))
+                throw new HostError("limit", listProblem);
+            const paths = list.map((path) => ownFile(path, this.fileRoots, "shader", VIDEO_PROCESSING_LIMITS.shaderBytes));
+            if (paths.length > 0 && !this.videoRender.gpu)
+                throw new HostError("unsupported", "shaders need GPU rendering; the player renders in software");
+            const mine = [...this.videoShaders.handles]
+                .filter(([other]) => other !== id)
+                .reduce((sum, [, held]) => sum + held.length, 0);
+            const others = mine + this.videoShaders.others;
+            if (others + paths.length > VIDEO_PROCESSING_LIMITS.shaders)
+                throw new HostError("limit", `at most ${VIDEO_PROCESSING_LIMITS.shaders} shaders across all plugins: ${others} are in use, this list has ${paths.length}`);
+            if (paths.length > 0)
+                this.videoShaders.handles.set(id, paths);
+            else
+                this.videoShaders.handles.delete(id);
+            return { state: this.source.phase === "ready" ? "applied" : "waiting" };
+        },
         "timeline.set": (p) => {
             if (p.sourceId !== undefined &&
                 p.sourceId !== this.source.stamp.generation)
@@ -4212,6 +4480,30 @@ export class TestHost {
                     status: "failed",
                     error: { code: "invalid", message: (problem ?? blend ?? delay) },
                 });
+            // `lut3d` files: the plugin's own `.cube` files (`plugin_files.rs`).
+            if (stage === "video")
+                for (const node of (p.nodes ?? []))
+                    if (node.kind === "lut3d") {
+                        let cube;
+                        try {
+                            const real = ownFile(node.file, this.fileRoots, "lut3d file", VIDEO_PROCESSING_LIMITS.lutBytes);
+                            cube = /\.cube$/i.test(real)
+                                ? cubeProblem(real)
+                                : "lut3d file must be a .cube file";
+                        }
+                        catch (error) {
+                            const { code, message } = error;
+                            return finish({ status: "failed", error: { code, message } });
+                        }
+                        if (cube)
+                            return finish({
+                                status: "failed",
+                                error: {
+                                    code: "invalid",
+                                    message: `lut3d file ${node.file}: ${cube}`,
+                                },
+                            });
+                    }
             if (this.source.phase !== "ready")
                 return finish({
                     status: "failed",
@@ -4750,6 +5042,24 @@ export class TestHost {
         },
     };
 }
+/** Lines `vestra-plugin test` printed already (one per plugin and reasons). */
+const told = new Set();
+/**
+ * Under `vestra-plugin test` (`VESTRA_PLUGIN_RESIDENCY=1`): say once per
+ * test file why the plugin would keep running after it starts.
+ */
+function tellResidency(host) {
+    if (process.env.VESTRA_PLUGIN_RESIDENCY !== "1")
+        return;
+    const reasons = host.keepsRunning;
+    if (!reasons.length)
+        return;
+    const line = `${host.manifestId} keeps running while idle (lazy activation): ${reasons.join("; ")}`;
+    if (told.has(line))
+        return;
+    told.add(line);
+    console.log(`# ${line}`);
+}
 /**
  * Activate a plugin against a test host, the way the player's runner does:
  * build the `plugin` object, call `activate(plugin)`, wait for every
@@ -4844,6 +5154,8 @@ export async function startPlugin(activate, options = {}) {
     for (const [key, value] of options.sessionStorage ?? [])
         host.sessionStorage.set(key, sortedJson(value));
     mkdirSync(data, { recursive: true });
+    if (host.fileRoots.length === 0)
+        host.fileRoots = [directory, data];
     const instance = await createPlugin(host, manifest, directory, data, host.app);
     await activate(instance.plugin);
     // Like the player: a position or resolver another plugin holds is not an
@@ -4859,6 +5171,7 @@ export async function startPlugin(activate, options = {}) {
         }
     }
     await host.settle();
+    tellResidency(host);
     return {
         /** The test host the plugin talks to. */
         host,