@vestra-player/sdk 1.5.38 → 1.5.39

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.5.39
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`, no new capability. The new API needs player 0.5.20 (`"minPlayerVersion": "0.5.20"`): older players refuse the new node kinds with `invalid` and the shader request as unknown, which shows as a `failed` handle. A plugin that uses none of it sees no difference; `plugin.video.render()` (its `shaders` included) behaves as before.
+
+- **Shader channel `plugin.video.shaders(id?)`** (player 0.5.20, `processing.video`): this plugin's own mpv user shaders, with any number of plugins holding handles at the same time (`render()` keeps its single owner). `set(paths)` sends the handle's whole list (last write wins), `clear()` and `dispose()` withdraw it, `status`/`onStatus` as for filters. The player joins every list after the render options' own `shaders`, in a stable order: built-in plugins, then installed plugins in the order they were first installed, then development loads; ties by plugin id, a plugin's handles by id. At most 16 shaders across all handles (`limit`; the render options keep their own 16). Files must be the plugin's own (package or data directory after following links, at most 16 MiB; `invalid` elsewhere, `missing` when absent). GPU rendering only (`unsupported` under software rendering; when the player switches to software during the run every handle hears `unsupported` and its list is removed, to be set again once the player draws on the GPU); never in snapshots or exports. A compile failure is pushed to every handle with shaders not yet told; whenever more than one holder has shaders on (other handles or `render().shaders`), the message says the player cannot tell whose shader failed. Handle ids, like `lut3d` paths, refuse C0 and C1 control characters. New type `VideoShaders`.
+- **`convolution` and `lut3d` video nodes** (player 0.5.20): `{ kind: "convolution", planes }` takes one integer kernel per plane (`ConvolutionPlane`: `mode` `square` with 9, 25 or 49 entries, or `row`/`column` with an odd count up to 49; `rdiv`, `bias`), strictly checked; `{ kind: "lut3d", file, interpolation }` recolours with a `.cube` file from the plugin's package or data directory (`LUT_3D_SIZE` 2–65, 16 MiB, no `[` or `]` in the path). Both run in the filter chain like the other nodes, so they apply to processed snapshots and exports, and they need frames in memory (copy-back decoding). New type `ConvolutionPlane`.
+- **`VIDEO_PROCESSING_LIMITS`** (`@vestra-player/sdk/testing`): the bounds above (including `lutPathBytes`, 4096), in the generated table of _Limits_.
+- **`TestHost`**: `videoShaders` (this plugin's lists by id, `others` for other plugins' count), `fileRoots` (the package and data directory `startPlugin` sets), `failVideoShaders(id, message)`; `failVideoRender("unsupported")` also tells the shader handles and removes their lists; `processing.replace` checks `lut3d` files like the player.
+- Corrected: the reference no longer says only macOS renders on the GPU. Windows has GPU rendering since player 0.5.14 (Video ▸ GPU Rendering (Experimental), off by default): `RenderOptions`, `SystemInfo.rendering`, `PlaybackStats.backend`, `RenderingReasonCode` (`default`, `no-gpu-backend`) and the `TestHost.rendering` example say so.
+
 ## 1.5.38
 
 **Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The marks below are read by player 0.5.18 and later; older players ignore them, and a plugin built with an older SDK keeps working (the player builds the `plugin` object with its own SDK). What may change for a plugin is the player's lazy activation, off by default in player 0.5.18 and turned on in a later release: a plugin that holds nothing only its process can serve is stopped while idle and started on its next use, so state kept only in variables is lost between uses (keep it in `plugin.storage.session`).

package/dist/api-requests.js

@@ -118,6 +118,7 @@ export const API_REQUESTS = Object.freeze({
     ],
     "Plugin.video.view": [{ method: "video.view.set" }],
     "Plugin.video.render": [{ method: "video.render.set" }],
+    "Plugin.video.shaders": [{ method: "video.shaders.set" }],
     "Plugin.audio.filter": [
         { method: "processing.replace", params: { stage: "audio" } },
     ],

package/dist/host-capabilities.js

@@ -191,6 +191,7 @@ export const HOST_CAPABILITIES = {
                 { name: "video.view.release", needs: "processing.video" },
                 { name: "video.render.set", needs: "processing.video" },
                 { name: "video.render.release", needs: "processing.video" },
+                { name: "video.shaders.set", needs: "processing.video" },
             ],
             name: "processing.video",
             requires: ["playback.read"],

package/dist/player-runtime.d.ts

@@ -18,6 +18,7 @@ export { BINDING_INPUTS } from "./plugin/bindings.ts";
 export { OSD_LIMITS } from "./plugin/osd.ts";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.ts";
 export { SUBTITLE_LIMITS } from "./plugin/subtitles.ts";
+export { VIDEO_PROCESSING_LIMITS } from "./processing.ts";
 export { THEME_PALETTES } from "./palettes.ts";
 export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.ts";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.ts";

package/dist/player-runtime.js

@@ -16,6 +16,7 @@ export { BINDING_INPUTS } from "./plugin/bindings.js";
 export { OSD_LIMITS } from "./plugin/osd.js";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.js";
 export { SUBTITLE_LIMITS } from "./plugin/subtitles.js";
+export { VIDEO_PROCESSING_LIMITS } from "./processing.js";
 export { THEME_PALETTES } from "./palettes.js";
 export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.js";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.js";

package/dist/plugin/scope.d.ts

@@ -15,6 +15,7 @@ export declare class ScopeImpl implements Plugin {
     readonly video: {
         view: () => import("./types.ts").VideoView;
         render: () => import("./types.ts").RenderOptions;
+        shaders: (id?: string) => import("./types.ts").VideoShaders;
         upscaling: import("./types.ts").VideoUpscaling;
         filter(id: string): import("./types.ts").VideoFilter;
     };

package/dist/plugin/scope.js

@@ -10,6 +10,7 @@ import { i18n } from "./language.js";
 import { player } from "./player.js";
 import { audioFilters, videoFilters } from "./filters.js";
 import { videoRender, videoView } from "./view.js";
+import { videoShaders } from "./shaders.js";
 import { subtitles } from "./subtitles.js";
 import { mediaCapture } from "./media.js";
 import { resolvers } from "./resolvers.js";
@@ -49,6 +50,7 @@ export class ScopeImpl {
         ...videoFilters(this),
         view: () => videoView(this),
         render: () => videoRender(this),
+        shaders: (id) => videoShaders(this, id),
         upscaling: videoUpscaling(this),
     };
     audio = audioFilters(this);

package/dist/plugin/shaders.d.ts

@@ -0,0 +1,9 @@
+import type { ScopeImpl } from "./scope.ts";
+import type { VideoShaders } from "./types.ts";
+/** The handle id when `shaders()` is called without one. */
+export declare const DEFAULT_SHADERS_ID = "shaders";
+/** Why `paths` would be refused here (`null` when it may be sent). */
+export declare function shaderListProblem(paths: unknown): string | null;
+/** Why a handle id would be refused (`null` when valid). */
+export declare function shaderIdProblem(id: unknown): string | null;
+export declare function videoShaders(scope: ScopeImpl, id?: string): VideoShaders;

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. */
@@ -1341,6 +1344,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 +1742,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 +1752,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();
      * ```
      *

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,7 +82,8 @@ 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 { THEMES } from "./appearance.js";
@@ -107,6 +108,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 +191,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",
@@ -1311,6 +1378,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 +1749,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 +1759,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();
      * ```
      *
@@ -3985,6 +4124,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 +4379,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",
@@ -4844,6 +5035,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