@vestra-player/sdk 1.5.37 → 1.5.39

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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`).
+
+- **Mirror subscriptions** (player 0.5.18): the SDK's own subscriptions that keep `plugin.player.state`, `plugin.window.state`, `plugin.timeline.marks`, `plugin.subtitles.state`, `plugin.appearance`, `plugin.resolvers.fileTypes` and panel positions current are sent as `events.subscribe { event, mirror: true }`. When the plugin adds a listener (an `onChange`, `onEnd`, `onFileTypesChange`) or a binding that reads that state (a command's `enabled`, `checked`, `busy` or `reason` function, a view's `bind`), the SDK sends `events.subscribe { event }` again; when the last one goes, `events.subscribe { event, mirror: true }`. A change made while the plugin activates is sent before it reports ready, so the player sees it when it classifies the plugin. The player keeps a plugin whose subscriptions are all mirrors parkable; the plugin sees no difference.
+- **`PluginInfo.process`** (player 0.5.18, optional): for a running plugin, `"running"` while its process runs, `"idle"` while the player stopped it because nothing used it (its entries stay and its next use starts it). `state` stays `"running"`, and a change of `process` alone does not fire `packages.onChange`.
+- **`TestHost.listening`**: the subscribed events the plugin really listens to (`subscriptions` without the mirrors).
+- _Plugins_ (concepts) has a new section, _Idle plugins are stopped_: what stays while a plugin is stopped, what keeps it running (listeners, bindings that read state, windows, panels, chains, streams…) and what does not (network requests, timers and promises the player does not see: as in Chrome Manifest V3, keep what they need in session storage).
+
 ## 1.5.37
 
 **Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The new API needs player 0.5.16 (`"minPlayerVersion": "0.5.16"`): older players do not load a plugin that declares the new capability `video.upscaling` (an unknown capability). A plugin that does not use it sees no difference.

package/README.md

@@ -15,6 +15,7 @@
   <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a> ·
   <a href="https://vestrasys.github.io/vestra-player-sdk/llms.txt">llms.txt</a>
 </p>
+
 ## Features
 
 - **One typed API** (`vestra/1`) for commands and menus, windows, panels, settings pages, on-screen messages, playback state and control, video and audio filters, and generated streams.

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/appearance.js

@@ -29,6 +29,7 @@ class AppearanceService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("appearance.changed", (data) => {
             const event = data;
             const language = preference(event?.language);
@@ -39,7 +40,7 @@ class AppearanceService {
             const theme = event?.theme;
             if (theme && THEMES.includes(theme))
                 this.accept(theme);
-        });
+        }, "events", true);
     }
     accept(theme) {
         if (theme === this.theme)
@@ -51,7 +52,13 @@ class AppearanceService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("appearance.changed");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 const appearanceOf = (runtime) => runtime.service("appearance", () => new AppearanceService(runtime));
@@ -60,6 +67,7 @@ export function appearance(scope) {
     return {
         get theme() {
             service().start();
+            scope.runtime.reading("appearance.changed");
             return service().theme;
         },
         onChange(listener) {
@@ -80,6 +88,7 @@ export function appearance(scope) {
         },
         get language() {
             service().start();
+            scope.runtime.reading("appearance.changed");
             return service().language;
         },
         async setLanguage(language) {

package/dist/plugin/packages.js

@@ -164,6 +164,9 @@ const info = (plugin) => Object.freeze({
         ...(warning.slot === undefined ? {} : { slot: warning.slot }),
         ...(warning.owner === undefined ? {} : { owner: warning.owner }),
     }))),
+    ...(plugin.process === "running" || plugin.process === "idle"
+        ? { process: plugin.process }
+        : {}),
     ...(plugin.display
         ? {
             display: Object.freeze({

package/dist/plugin/player.js

@@ -116,7 +116,9 @@ export class PlayerService {
     output;
     constructor(runtime) {
         this.runtime = runtime;
-        runtime.on("source.state", (data) => this.accept(data));
+        // The SDK's copy of the state (a mirror): a plugin listens through
+        // `watch` and the bindings that read `state`.
+        runtime.on("source.state", (data) => this.accept(data), "events", true);
         this.output = new Latest(async ({ volume, muted }) => {
             if (volume !== undefined)
                 await runtime.host.playback.set("volume", volume);
@@ -144,9 +146,11 @@ export class PlayerService {
     }
     watch(watcher) {
         this.#watchers.add(watcher);
+        const held = this.runtime.hold("source.state");
         return {
             dispose: async () => {
                 this.#watchers.delete(watcher);
+                await held.dispose();
             },
         };
     }
@@ -429,6 +433,7 @@ export function player(scope) {
     const service = () => playerOf(scope.runtime);
     return {
         get state() {
+            scope.runtime.reading("source.state");
             return service().state;
         },
         onChange(listener) {

package/dist/plugin/resolvers.js

@@ -26,11 +26,12 @@ class FileTypesService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("resolvers.fileTypes", (data) => {
             const types = data?.fileTypes;
             if (Array.isArray(types) && types.every((t) => typeof t === "string"))
                 this.accept(types);
-        });
+        }, "events", true);
         // What changed between the start-up read and the subscription.
         const window = windowOf(this.#runtime);
         void window.read().then(() => {
@@ -50,7 +51,13 @@ class FileTypesService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("resolvers.fileTypes");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 const fileTypesOf = (runtime) => runtime.service("fileTypes", () => new FileTypesService(runtime));
@@ -58,6 +65,7 @@ export const resolvers = (scope) => ({
     get fileTypes() {
         const service = fileTypesOf(scope.runtime);
         service.start();
+        scope.runtime.reading("resolvers.fileTypes");
         return service.types;
     },
     onFileTypesChange(listener) {

package/dist/plugin/runtime.d.ts

@@ -53,15 +53,28 @@ export declare class Runtime {
     starting<T>(work: Promise<T>, report: (error: unknown) => void): Promise<T>;
     activated(): Promise<void>;
     bind(evaluate: () => void): Disposable;
+    /**
+     * A service's state for `event` is read: a binding evaluated now depends
+     * on it, so the event counts as listened to while the binding reads it.
+     */
+    reading(event: string): void;
     /** Coalesce: one evaluation pass per microtask turn, however many changes. */
     invalidate(): void;
     /**
      * Host events with one `events.subscribe` per name, however many listeners.
      * Without the `events` capability the listener simply never fires.
+     * `mirror`: the SDK's own copy of the state (`plugin.player.state` and
+     * the like), not a listener of the plugin's (see {@link EventGroup}).
      */
     on(event: string, listener: Listener, 
     /** The capability the event needs; `null`: none. */
-    needs?: string | null): Disposable;
+    needs?: string | null, mirror?: boolean): Disposable;
+    /**
+     * Count `event` as listened to while held: a watcher of a service's
+     * state, a binding that reads it. Nothing when nothing subscribed to it
+     * (no capability, or the service did not start).
+     */
+    hold(event: string): Disposable;
     /** Raw transport events the host pushes without a subscription. */
     raw(event: string, listener: Listener): Disposable;
 }

package/dist/plugin/runtime.js

@@ -87,7 +87,10 @@ export class Runtime {
     startup = new Set();
     #activating = true;
     #transport;
-    #bindings = new Set();
+    /** Each binding with the events whose state it read last time (held). */
+    #bindings = new Map();
+    /** The events read by the binding being evaluated. */
+    #reads;
     #scheduled = false;
     #events = new Map();
     views = new Map();
@@ -149,14 +152,47 @@ export class Runtime {
         this.#activating = false;
     }
     bind(evaluate) {
-        this.#bindings.add(evaluate);
+        const held = new Map();
+        this.#bindings.set(evaluate, held);
         this.invalidate();
         return {
             dispose: async () => {
+                if (this.#bindings.get(evaluate) !== held)
+                    return;
                 this.#bindings.delete(evaluate);
+                for (const hold of held.values())
+                    await hold.dispose();
+                held.clear();
             },
         };
     }
+    /**
+     * A service's state for `event` is read: a binding evaluated now depends
+     * on it, so the event counts as listened to while the binding reads it.
+     */
+    reading(event) {
+        this.#reads?.add(event);
+    }
+    /** Evaluate one binding, holding the events whose state it read. */
+    #evaluate(evaluate, held) {
+        const reads = new Set();
+        const outer = this.#reads;
+        this.#reads = reads;
+        try {
+            evaluate();
+        }
+        finally {
+            this.#reads = outer;
+            for (const [event, hold] of held)
+                if (!reads.has(event)) {
+                    held.delete(event);
+                    void hold.dispose();
+                }
+            for (const event of reads)
+                if (!held.has(event))
+                    held.set(event, this.hold(event));
+        }
+    }
     /** Coalesce: one evaluation pass per microtask turn, however many changes. */
     invalidate() {
         if (this.#scheduled)
@@ -164,9 +200,11 @@ export class Runtime {
         this.#scheduled = true;
         queueMicrotask(() => {
             this.#scheduled = false;
-            for (const evaluate of this.#bindings) {
+            for (const [evaluate, held] of [...this.#bindings]) {
+                if (this.#bindings.get(evaluate) !== held)
+                    continue;
                 try {
-                    evaluate();
+                    this.#evaluate(evaluate, held);
                 }
                 catch (error) {
                     console.error(`[${this.manifest.id}] binding failed:`, error);
@@ -177,36 +215,89 @@ export class Runtime {
     /**
      * Host events with one `events.subscribe` per name, however many listeners.
      * Without the `events` capability the listener simply never fires.
+     * `mirror`: the SDK's own copy of the state (`plugin.player.state` and
+     * the like), not a listener of the plugin's (see {@link EventGroup}).
      */
     on(event, listener, 
     /** The capability the event needs; `null`: none. */
-    needs = "events") {
+    needs = "events", mirror = false) {
         let entry = this.#events.get(event);
+        const created = !entry;
         if (!entry) {
-            entry = { listeners: new Set() };
+            entry = { listeners: new Set(), active: 0 };
             this.#events.set(event, entry);
-            if (needs === null || this.can(needs)) {
-                const group = entry;
-                entry.off = this.host.events.subscribe(event, (data) => {
-                    for (const each of [...group.listeners])
-                        each(data);
-                });
-                this.starting(entry.off, (error) => console.error(`[${this.manifest.id}] subscribe ${event}:`, error));
-            }
         }
-        entry.listeners.add(listener);
         const group = entry;
+        group.listeners.add(listener);
+        if (!mirror)
+            group.active++;
+        if (created && (needs === null || this.can(needs))) {
+            group.told = group.active > 0;
+            group.off = this.host.events.subscribe(event, (data) => {
+                for (const each of [...group.listeners])
+                    each(data);
+            }, !group.told);
+            this.starting(group.off, (error) => console.error(`[${this.manifest.id}] subscribe ${event}:`, error));
+        }
+        else
+            this.#tell(event, group);
+        let listening = true;
         return {
             dispose: async () => {
+                if (!listening)
+                    return;
+                listening = false;
                 group.listeners.delete(listener);
-                if (group.listeners.size || this.#events.get(event) !== group)
+                if (!mirror)
+                    group.active--;
+                if (this.#events.get(event) !== group)
                     return;
+                if (group.listeners.size)
+                    return this.#tell(event, group);
                 this.#events.delete(event);
                 const off = await group.off?.catch(() => undefined);
                 await off?.().catch(() => { });
             },
         };
     }
+    /**
+     * Count `event` as listened to while held: a watcher of a service's
+     * state, a binding that reads it. Nothing when nothing subscribed to it
+     * (no capability, or the service did not start).
+     */
+    hold(event) {
+        const group = this.#events.get(event);
+        if (!group)
+            return { dispose: async () => { } };
+        group.active++;
+        this.#tell(event, group);
+        let held = true;
+        return {
+            dispose: async () => {
+                if (!held)
+                    return;
+                held = false;
+                group.active--;
+                if (this.#events.get(event) === group)
+                    this.#tell(event, group);
+            },
+        };
+    }
+    /** Tell the player when `group` changes between mirror and listener. */
+    #tell(event, group) {
+        const off = group.off;
+        const active = group.active > 0;
+        if (!off || group.told === active)
+            return;
+        group.told = active;
+        // Part of activation while it runs: the player classifies the plugin
+        // at its ready, which must see this mark. A failure is not one of
+        // activation (an older player never refuses it).
+        const told = off
+            .then(() => this.host.events.listen(event, active))
+            .catch(() => { });
+        this.starting(told, () => { });
+    }
     /** Raw transport events the host pushes without a subscription. */
     raw(event, listener) {
         const off = this.#transport.on(event, listener);

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/subtitles.js

@@ -62,6 +62,8 @@ export const SUBTITLE_LIMITS = Object.freeze({
     /** Loads of every plugin in progress at the same time (8). */
     uploads: 8,
 });
+/** The events the subtitle state follows (it has none of its own). */
+const EVENTS = ["source.state", "playback.backend"];
 const raws = new WeakMap();
 const targets = new WeakMap();
 const CHUNK = 32 * 1024;
@@ -85,6 +87,7 @@ class SubtitleService {
     constructor(runtime) {
         this.#runtime = runtime;
         // No subtitle event exists: re-read when the source or backend changes.
+        // Mirrors: a plugin listens through `watch` and bindings.
         runtime.on("source.state", (data) => {
             const raw = data;
             const source = `${raw.stamp.generation}:${raw.phase}`;
@@ -92,8 +95,8 @@ class SubtitleService {
                 return;
             this.#source = source;
             void this.refresh().catch(() => { });
-        });
-        runtime.on("playback.backend", () => void this.refresh().catch(() => { }));
+        }, "events", true);
+        runtime.on("playback.backend", () => void this.refresh().catch(() => { }), "events", true);
         this.style = new Latest(async ({ style, options }) => {
             const expected = await this.expected(options);
             await this.#mutate(++this.#operation, (operationId) => runtime.host.subtitles.style({
@@ -106,12 +109,20 @@ class SubtitleService {
     }
     watch(watcher) {
         this.#watchers.add(watcher);
+        const held = EVENTS.map((event) => this.#runtime.hold(event));
         return {
             dispose: async () => {
                 this.#watchers.delete(watcher);
+                for (const hold of held.splice(0))
+                    await hold.dispose();
             },
         };
     }
+    /** A binding that reads the state follows both events. */
+    reading() {
+        for (const event of EVENTS)
+            this.#runtime.reading(event);
+    }
     /** Keep the newest view: older generations and older revisions are dropped. */
     accept(raw) {
         const old = this.raw;
@@ -258,6 +269,7 @@ export function subtitles(scope) {
     const host = () => scope.runtime.host.subtitles;
     return {
         get state() {
+            service().reading();
             return service().state;
         },
         onChange(listener) {