@vestra-player/sdk 1.5.38 → 1.5.40

package/dist/plugin/shaders.js

@@ -0,0 +1,160 @@
+/**
+ * The shader channel `plugin.video.shaders(id)` (SDK 1.5.39, player
+ * 0.5.20): this plugin's own mpv user shaders, joined by the player with
+ * every other plugin's in a stable order. Unlike `video.render()` any
+ * number of plugins hold one at a time; each handle sends its whole list
+ * (last write wins) and the player answers `applied`, `waiting` (no ready
+ * media), or a failure.
+ */
+import { isAbsolute } from "node:path";
+import { failure, Latest, quiet } from "./runtime.js";
+import { playerOf } from "./player.js";
+import { hasControl, VIDEO_PROCESSING_LIMITS } from "../processing.js";
+/** The handle id when `shaders()` is called without one. */
+export const DEFAULT_SHADERS_ID = "shaders";
+/** Why `paths` would be refused here (`null` when it may be sent). */
+export function shaderListProblem(paths) {
+    if (!Array.isArray(paths) || paths.some((p) => typeof p !== "string"))
+        return "shaders must be an array of paths";
+    if (paths.length > VIDEO_PROCESSING_LIMITS.shaders)
+        return `at most ${VIDEO_PROCESSING_LIMITS.shaders} shaders across all plugins`;
+    const relative = paths.find((path) => !isAbsolute(path));
+    if (relative !== undefined)
+        return `shader path must be absolute: ${relative}`;
+    return null;
+}
+/** Why a handle id would be refused (`null` when valid). */
+export function shaderIdProblem(id) {
+    return typeof id === "string" &&
+        id.length > 0 &&
+        Buffer.byteLength(id) <= VIDEO_PROCESSING_LIMITS.shaderIdBytes &&
+        !hasControl(id)
+        ? null
+        : `shader handle id must be 1 to ${VIDEO_PROCESSING_LIMITS.shaderIdBytes} bytes without control characters`;
+}
+class ShaderHandle {
+    #scope;
+    #id;
+    #desired = [];
+    /** Something non-empty was sent: `dispose` withdraws it. */
+    #sent = false;
+    #status = { state: "waiting" };
+    #disposed = false;
+    #source = "";
+    #listeners = new Set();
+    #latest;
+    #watch;
+    #pushed;
+    constructor(scope, id) {
+        this.#scope = scope;
+        this.#id = id;
+        this.#latest = new Latest(async (paths) => {
+            if (paths.length > 0)
+                this.#sent = true;
+            const { state } = await scope.runtime.host.video.shadersSet(id, paths);
+            if (this.#desired === paths)
+                this.#report({ state });
+        });
+        // `waiting` becomes `applied` when media becomes ready: ask again.
+        this.#watch = playerOf(scope.runtime).watch((raw) => {
+            const source = `${raw.stamp.generation}:${raw.phase}`;
+            if (source === this.#source)
+                return;
+            const first = this.#source === "";
+            this.#source = source;
+            if (!first && this.#status.state === "waiting" && this.#sent)
+                this.#send();
+        });
+        this.#pushed = scope.runtime.raw("video.shaders.status", (data) => {
+            const { id: target, error } = data;
+            if (this.#disposed || target !== this.#id || !error)
+                return;
+            this.#fail(failure(error.code ?? "failed", error.message));
+        });
+        scope.add(this);
+    }
+    get status() {
+        return this.#status;
+    }
+    onStatus(listener) {
+        this.#listeners.add(listener);
+        return this.#scope.onDispose(() => {
+            this.#listeners.delete(listener);
+        });
+    }
+    set(paths) {
+        if (this.#disposed)
+            return;
+        const problem = shaderListProblem(paths);
+        if (problem) {
+            // Refused at once; what the player holds stays.
+            this.#fail(failure(problem.startsWith("at most") ? "limit" : "invalid", problem));
+            return;
+        }
+        this.#desired = [...paths];
+        this.#send();
+    }
+    clear() {
+        this.set([]);
+    }
+    #send() {
+        const paths = this.#desired;
+        this.#report({ state: "applying" });
+        quiet(this.#latest.push(paths).catch((error) => {
+            if (this.#desired === paths && !this.#disposed)
+                this.#fail(error);
+        }));
+    }
+    #fail(error) {
+        this.#report({ state: "failed", error });
+        this.#scope.report(error);
+    }
+    #report(status) {
+        if (JSON.stringify(status) === JSON.stringify(this.#status) &&
+            status.state !== "failed")
+            return;
+        this.#status = status;
+        for (const listener of this.#listeners)
+            this.#scope.run(listener, status);
+        this.#scope.update();
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#scope.forget(this);
+        this.#latest.stop();
+        await this.#watch.dispose();
+        await this.#pushed.dispose();
+        this.#scope.runtime.services.delete(`video.shaders:${this.#id}`);
+        // Withdraw this handle's shaders; refused (and moot) once stopped: the
+        // player removes a stopped plugin's shaders itself.
+        if (this.#sent)
+            await this.#scope.runtime.host.video
+                .shadersSet(this.#id, [])
+                .catch(() => { });
+    }
+}
+export function videoShaders(scope, id) {
+    const runtime = scope.runtime;
+    if (!runtime.can("processing.video"))
+        throw failure("capability", "processing.video must be declared in manifest");
+    const name = id ?? DEFAULT_SHADERS_ID;
+    const problem = shaderIdProblem(name);
+    if (problem)
+        throw failure("invalid", problem);
+    const service = `video.shaders:${name}`;
+    if (runtime.services.has(service))
+        throw new Error(`a shader handle "${name}" exists; reuse it`);
+    runtime.services.set(service, true);
+    const handle = new ShaderHandle(scope, name);
+    return {
+        set: (paths) => handle.set(paths),
+        clear: () => handle.clear(),
+        get status() {
+            return handle.status;
+        },
+        onStatus: (listener) => handle.onStatus(listener),
+        dispose: () => handle.dispose(),
+    };
+}

package/dist/plugin/testing.d.ts

@@ -15,6 +15,7 @@ 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 { VIDEO_PROCESSING_LIMITS } from "../processing.ts";
 import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingReason, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
 import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
@@ -41,6 +42,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. */
@@ -268,7 +271,26 @@ export interface FakeCommand {
          */
         reason?: string | null;
     };
-    /** The command state the player last received (after the update pass). */
+    /**
+     * The conditions the plugin sent for `enabled` and `checked`
+     * (`plugin.when`, wire form), `undefined` without. Like the player, the
+     * host evaluates them in {@link FakeCommand.state} against `source`,
+     * `mainWindow.fullscreen`, `appearance` and `language`.
+     *
+     * @since 1.5.40
+     */
+    when?: {
+        /** The condition of `enabled`. */
+        enabled?: Json;
+        /** The condition of `checked`. */
+        checked?: Json;
+    };
+    /**
+     * The command state as the player shows it: what the plugin last sent
+     * (after the update pass), with the fields given as conditions
+     * (`plugin.when`) evaluated now. With an `enabled` condition, `reason`
+     * is `null` while the command is enabled and not busy.
+     */
     state: {
         /** `false` when the plugin disabled the command. */
         enabled: boolean;
@@ -545,6 +567,16 @@ export declare class TestHost implements Transport {
      * @since 1.5.38
      */
     readonly listening: Set<string>;
+    /**
+     * 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
+     */
+    readonly listeningWhy: Map<string, string[]>;
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with
@@ -1341,6 +1373,64 @@ export declare class TestHost implements Transport {
      * @since 1.0.0
      */
     failVideoRender(code: "failed" | "unsupported", message: string): void;
+    /**
+     * 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
+     */
+    readonly videoShaders: {
+        /** This plugin's lists by handle id; a cleared handle has none. */
+        handles: Map<string, string[]>;
+        /** Shaders other plugins hold (0–16). */
+        others: number;
+    };
+    /**
+     * 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: string[];
+    /**
+     * 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: string, message: string): void;
     /**
      * The player's processing (filter) state. Wire-level; may change in minor
      * versions. `resources` holds each `video.filter` / `audio.filter` chain the
@@ -1681,9 +1771,9 @@ export declare class TestHost implements Transport {
      * 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),
@@ -1691,7 +1781,7 @@ export declare class TestHost implements Transport {
      * });
      * 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();
      * ```
      *
@@ -2527,6 +2617,32 @@ export declare class TestHost implements Transport {
      * @since 1.0.0
      */
     close(): void;
+    /**
+     * 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(): string[];
 }
 /**
  * Activate a plugin against a test host, the way the player's runner does: