@vestra-player/sdk 1.5.38 → 1.5.40

package/dist/plugin/types.d.ts

@@ -9,11 +9,11 @@
  * object, so a built plugin has no runtime dependency on this package.
  */
 import type { Json } from "../wire.ts";
-import type { AudioNode, VideoNode } from "../processing.ts";
+import type { AudioNode, ConvolutionPlane, VideoNode } from "../processing.ts";
 import type { SubtitleStyle } from "../subtitles.ts";
 import type { ResolvedMedia } from "../source-resolvers.ts";
 import type { MediaJob } from "../media.ts";
-export type { Json, AudioNode, VideoNode, SubtitleStyle, ResolvedMedia };
+export type { Json, AudioNode, ConvolutionPlane, VideoNode, SubtitleStyle, ResolvedMedia, };
 /**
  * Anything that owns player-side or local resources: every handle the API
  * returns (commands, windows, panels, filters, snapshots, listeners…).
@@ -204,6 +204,13 @@ export type PluginError = Error & {
 export interface Scope extends Disposable {
     /** Menu commands and their default bindings (`commands`). */
     readonly commands: Commands;
+    /**
+     * Conditions on the player's own state for a command's `enabled` and
+     * `checked` (SDK 1.5.40, player 0.5.21): the player evaluates them, so
+     * the menu follows playback even while the plugin is stopped. See
+     * {@link When}.
+     */
+    readonly when: When;
     /** Tool windows from `.slint` files (`ui.window`). */
     readonly windows: Windows;
     /** Docked panels: bottom bar, sidebar and backdrop (`ui.mount`). */
@@ -214,10 +221,11 @@ export interface Scope extends Disposable {
     readonly player: Player;
     /**
      * Video processing: this plugin's filter chain, the display layer, the
-     * GPU render options and the GPU's video upscaler. The first three need
-     * `processing.video` and `playback.read`; the filter chain also needs
-     * `events` (without it the SDK never sees the media become ready and the
-     * chain stays `waiting`). The upscaler needs `video.upscaling` only.
+     * GPU render options, this plugin's shaders and the GPU's video
+     * upscaler. The first four need `processing.video` and `playback.read`;
+     * the filter chain also needs `events` (without it the SDK never sees
+     * the media become ready and the chain stays `waiting`). The upscaler
+     * needs `video.upscaling` only.
      */
     readonly video: {
         /**
@@ -250,6 +258,24 @@ export interface Scope extends Disposable {
          *   while the first handle is not disposed.
          */
         render(): RenderOptions;
+        /**
+         * This plugin's own GPU shaders named `id` (default `"shaders"`;
+         * needs `processing.video`; SDK 1.5.39, player 0.5.20). Unlike
+         * {@link Scope.video | render()}, every plugin may hold shader
+         * handles at the same time; the player joins their lists. Nothing is
+         * sent until the first `set()`.
+         *
+         * @param id - Local name of the handle, 1–128 bytes, unique within
+         *   the plugin.
+         * @returns A {@link VideoShaders} owned by this scope.
+         * @throws `capability` (throws) The manifest does not declare
+         *   `processing.video`.
+         * @throws `invalid` (throws) `id` is empty, longer than 128 bytes or
+         *   has control characters.
+         * @throws `Error` without a code (throws) A second handle with the
+         *   same `id` while the first is not disposed.
+         */
+        shaders(id?: string): VideoShaders;
         /**
          * The GPU's video upscaler (NVIDIA RTX Video Super Resolution on
          * Windows; needs `video.upscaling`, player 0.5.16): whether it works
@@ -561,6 +587,217 @@ export interface CommandState {
  * @category Commands
  */
 export type Bindable<T> = T | (() => T);
+/**
+ * A condition on the player's own state, from {@link Scope.when}, for a
+ * command's `enabled` or `checked`. The player evaluates it, again on
+ * every change of that state, whether or not the plugin runs.
+ *
+ * @remarks
+ * Combine conditions with `and`, `or` and `not`; each returns a new
+ * condition and leaves the original as it was. A condition is data: it
+ * reads nothing in the plugin and keeps no listener, so a plugin whose
+ * menu state is made of conditions may be stopped while idle (lazy
+ * activation) and its menu stays current. A function (see {@link Bindable})
+ * keeps working; one that reads `plugin.player.state` or another service's
+ * state keeps the plugin running so the SDK can evaluate it.
+ *
+ * @capability commands
+ *
+ * @example Enable an item while a frame can be saved
+ * "Save Snapshot" is greyed out with its reason unless a media file is
+ * open at a frame the player can capture. The condition is sent with the
+ * command and evaluated by the player, so the item follows playback even
+ * while the plugin is stopped; with an `enabled` condition the player
+ * shows the `reason` only while the item is disabled.
+ * ```ts
+ * declare function saveSnapshot(): Promise<void>;
+ * // ---cut---
+ * const { when } = plugin;
+ * plugin.commands.add({
+ *   id: "save",
+ *   path: ["@video", "Save Snapshot"],
+ *   enabled: when.can("snapshot").and(when.phase("ready", "ended"), when.stream.not()),
+ *   reason: "No frame to capture", // shown only while disabled
+ *   run: saveSnapshot,
+ * });
+ * ```
+ *
+ * @since 1.5.40
+ * @category Commands
+ */
+export interface Condition {
+    /**
+     * True when this condition and every one of `others` hold.
+     *
+     * @example Combine two conditions with and
+     * The item is enabled only while a file plays in fullscreen. `and`
+     * returns a new condition; `when.playing` itself is unchanged.
+     * ```ts
+     * const { when } = plugin;
+     * const playingFullscreen = when.playing.and(when.fullscreen);
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    and(...others: Condition[]): Condition;
+    /**
+     * True when this condition or one of `others` holds.
+     *
+     * @example Combine two conditions with or
+     * The item is enabled while a file plays or is paused. `or` returns a
+     * new condition that holds when either of the two holds.
+     * ```ts
+     * const { when } = plugin;
+     * const active = when.playing.or(when.paused);
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    or(...others: Condition[]): Condition;
+    /**
+     * True when this condition does not hold.
+     *
+     * @example Negate a condition with not
+     * An "Enter Fullscreen" item is enabled only outside fullscreen. `not`
+     * returns the opposite condition; the player evaluates it on every
+     * window change.
+     * ```ts
+     * const { when } = plugin;
+     * const windowed = when.fullscreen.not();
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    not(): Condition;
+}
+/**
+ * `plugin.when`: the vocabulary of conditions (SDK 1.5.40, player 0.5.21).
+ * It names only state the player owns: the source's phase, kind, pause
+ * and controls (the same names as {@link PlayerState}), fullscreen, the
+ * palette and the saved interface language.
+ *
+ * @remarks
+ * Give a condition as a command's `enabled` or `checked`
+ * ({@link CommandOptions}, {@link Command.set}). The player evaluates it
+ * and shows the result in menus, on keys and on bar buttons, again
+ * whenever that state changes, also while the plugin is stopped because
+ * nothing used it. With an `enabled` condition the player shows the
+ * command's `reason` only while the condition is false (or the command
+ * is busy), so a fixed reason is enough. Players before 0.5.21 have no
+ * `plugin.when` (declare `"minPlayerVersion": "0.5.21"`).
+ *
+ * State the vocabulary does not name (a plugin's own settings, an open
+ * window, a track list) stays a function or a value set with
+ * {@link Command.set}.
+ *
+ * @capability commands
+ *
+ * @example Check a palette item and follow the palette
+ * The Appearance submenu has one radio item per palette; the player
+ * checks the one in use, also after another plugin or the user changed
+ * it, and while this plugin is stopped. Nothing in the plugin listens to
+ * the palette.
+ * ```ts
+ * const { when } = plugin;
+ * for (const [id, title] of [["vestra", "Dark"], ["vestra-light", "Light"]] as const)
+ *   plugin.commands.add({
+ *     id: `theme.${id}`,
+ *     path: ["Settings", "Appearance", title],
+ *     radio: true,
+ *     checked: when.theme(id), // evaluated by the player, not the plugin
+ *     run: () => plugin.appearance.set(id),
+ *   });
+ * ```
+ *
+ * @since 1.5.40
+ * @category Commands
+ */
+export interface When {
+    /** A source is open: any phase but `empty` (loading, ready, ended, error). */
+    readonly open: Condition;
+    /** The source is loaded and can play (`phase` is `ready`). */
+    readonly ready: Condition;
+    /** The source is ready and not paused. */
+    readonly playing: Condition;
+    /** The source is ready and paused. */
+    readonly paused: Condition;
+    /** The source is a generated stream (`PlayerState.kind` is `stream`). */
+    readonly stream: Condition;
+    /** The main window is fullscreen. */
+    readonly fullscreen: Condition;
+    /**
+     * The source's `phase` is one of `phases`.
+     *
+     * @throws `TypeError` (throws) No phase, or one that is not a phase.
+     *
+     * @example Enable an item while a file is loaded or finished
+     * The item is enabled while the source is ready or has ended, as a
+     * snapshot needs a frame. The phases are those of `PlayerState.phase`.
+     * ```ts
+     * const { when } = plugin;
+     * const hasFrame = when.phase("ready", "ended");
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    phase(...phases: PlayerState["phase"][]): Condition;
+    /**
+     * The source allows `control`: `PlayerState.can[control]` is true.
+     *
+     * @throws `TypeError` (throws) `control` is not one of `PlayerState.can`.
+     *
+     * @example Enable a seek item only where seeking works
+     * "Jump to Middle" is greyed out on live streams that cannot seek.
+     * The player reads its own `can.seek` for the current source.
+     * ```ts
+     * const { when } = plugin;
+     * const seekable = when.can("seek");
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    can(control: keyof PlayerState["can"]): Condition;
+    /**
+     * The palette in use is `theme` (`plugin.appearance.theme`).
+     *
+     * @throws `TypeError` (throws) `theme` is not a palette of the player.
+     *
+     * @example Check the light palette's item
+     * The item carries a check mark while the light palette is in use,
+     * whoever switched to it.
+     * ```ts
+     * const { when } = plugin;
+     * const light = when.theme("vestra-light");
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    theme(theme: ThemeId): Condition;
+    /**
+     * The saved interface language is `language`
+     * (`plugin.appearance.language`: `"system"` or a locale).
+     *
+     * @throws `TypeError` (throws) `language` is not `"system"` or a locale.
+     *
+     * @example Check the Follow System item
+     * The item carries a check mark while the player follows the system's
+     * language; the player reads its own saved preference.
+     * ```ts
+     * const { when } = plugin;
+     * const followSystem = when.language("system");
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    language(language: LanguagePreference): Condition;
+}
 /**
  * A built-in top-level menu of the player, named in a command path as
  * `@<id>` or by its English key (see {@link CommandOptions.path}): Open,
@@ -788,15 +1025,24 @@ export interface CommandOptions {
      * a button without a path.
      */
     button?: CommandButton;
-    /** Whether the command can run (default true). */
-    enabled?: Bindable<boolean>;
-    /** Check mark (or radio dot with `radio`); `null` (default) draws none. */
-    checked?: Bindable<boolean | null>;
+    /**
+     * Whether the command can run (default true): a value, a function, or a
+     * {@link Condition} the player evaluates (`plugin.when`, SDK 1.5.40).
+     */
+    enabled?: Bindable<boolean> | Condition;
+    /**
+     * Check mark (or radio dot with `radio`); `null` (default) draws none.
+     * A {@link Condition} (`plugin.when`, SDK 1.5.40) draws the mark while
+     * it holds.
+     */
+    checked?: Bindable<boolean | null> | Condition;
     /** Busy state (default false); the player does not call `run` while busy. */
     busy?: Bindable<boolean>;
     /**
      * Why the command is disabled or busy (shown to the user): English
      * source text, or a {@link Text} for one with data in it (SDK 1.5.11).
+     * With an `enabled` {@link Condition} the player shows it only while the
+     * condition is false or the command is busy, so a fixed text is enough.
      */
     reason?: Bindable<TextValue | null>;
     /**
@@ -875,7 +1121,10 @@ export interface Command extends Disposable {
      * @since 1.0.0
      */
     set(state: Partial<{
-        [K in keyof CommandState]: Bindable<CommandState[K]>;
+        [K in "busy" | "reason"]: Bindable<CommandState[K]>;
+    } & {
+        enabled: Bindable<boolean> | Condition;
+        checked: Bindable<boolean | null> | Condition;
     }>): void;
     /**
      * Resolves when the host has registered the command. Rejects with
@@ -4055,8 +4304,10 @@ export interface SystemInfo {
      * Absent (`undefined`) on players before 0.5.12, which do not report it:
      * the renderer is then unknown, not software.
      *
-     * Today the player renders on the GPU on macOS and in software on
-     * Windows, Linux and without a user interface (see
+     * Today the player renders on the GPU on macOS, on Windows when the
+     * user turned on Video ▸ GPU Rendering (Experimental) (since version 0.5.14;
+     * off by default), and in software otherwise: on Windows by default, on
+     * Linux and without a user interface (see
      * [Platforms](../../docs/reference/platforms.md)); test this field
      * rather than {@link SystemInfo.os}.
      *
@@ -4954,9 +5205,11 @@ export interface SequenceProvider {
  */
 export interface PlaybackStats {
     /**
-     * The rendering path: "libmpv · GPU 渲染（OpenGL）" (GPU, macOS default) or
-     * "libmpv · 软件渲染" (software: Windows, Linux, headless, fallback).
-     * The strings are the player's display text.
+     * The rendering path: "libmpv · GPU 渲染（OpenGL）" (GPU on macOS, the
+     * default there), "libmpv · GPU 渲染（Direct3D）" (GPU on Windows, when
+     * turned on; version 0.5.14 and later) or "libmpv · 软件渲染" (software: Windows by
+     * default, Linux, headless, fallback). The strings are the player's
+     * display text in the interface language (shown here in Chinese).
      */
     backend: string;
     /** The playback session number. */
@@ -6357,7 +6610,11 @@ export interface RenderSettings {
     targetPeak: number;
     /** Per-scene peak estimation (where the GPU supports it). */
     peakDetect: boolean;
-    /** mpv user shaders (`.glsl`): absolute paths of existing files, at most 16, in order. */
+    /**
+     * mpv user shaders (`.glsl`): absolute paths of existing files, at most
+     * 16, in order. They run before the shaders of every plugin's
+     * {@link VideoShaders} handles.
+     */
     shaders: string[];
     /** Motion interpolation, resampled to the display's refresh rate. */
     interpolation: boolean;
@@ -6367,10 +6624,12 @@ export interface RenderSettings {
  * (`processing.video`). Single owner, like {@link VideoView}; the two are
  * independent handles.
  *
- * Platforms: only macOS renders on the GPU. Under software rendering
- * (Windows, Linux, headless, fallback) every `set` fails with
- * `unsupported`; {@link SystemInfo.rendering} tells which renderer draws
- * without creating the handle. macOS OpenGL 4.1 has no
+ * Platforms: macOS renders on the GPU by default; Windows does since
+ * version 0.5.14 of the player when the user turns on Video ▸ GPU Rendering
+ * (Experimental) (off by default, {@link Rendering}). Under software
+ * rendering (Windows by default, Linux, headless, fallback) every `set`
+ * fails with `unsupported`; {@link SystemInfo.rendering} tells which
+ * renderer draws without creating the handle. macOS OpenGL 4.1 has no
  * compute shaders, so `peakDetect` is accepted but has no effect; output
  * is always SDR.
  *
@@ -6379,7 +6638,8 @@ export interface RenderSettings {
  * 250-nit display; under software rendering the plugin hides its HDR menu.
  * `set` merges the values into the plugin's render options and the
  * player reports the result through `onStatus`: `failed` with
- * `unsupported` means the player renders in software (Windows, Linux).
+ * `unsupported` means the player renders in software (Linux, or Windows
+ * while GPU rendering is off).
  * ```ts
  * declare function hideHdrMenu(): void;
  * // ---cut---
@@ -6392,11 +6652,13 @@ export interface RenderSettings {
  *
  * @remarks
  * GPU renderer options (tone mapping, peak detection, shaders,
- * interpolation). Only the GPU renderer has them, which today means macOS;
+ * interpolation). Only the GPU renderer has them (macOS; Windows with GPU
+ * rendering turned on, version 0.5.14 and later);
  * under software rendering the handle is `failed` with `unsupported` after
  * the player's first answer to `render()` (reported to `onError` too), and so is
  * every `set`. Single owner, like {@link VideoView}. `set` never throws; the
- * result shows in `status`.
+ * result shows in `status`. For shaders that several plugins add at the
+ * same time, use {@link VideoShaders} (SDK 1.5.39).
  *
  * @capability processing.video, playback.read and events (like
  * {@link VideoFilter})
@@ -6423,7 +6685,9 @@ export interface RenderOptions extends Disposable {
     set(value: Partial<RenderSettings>): void;
     /**
      * `failed` with `unsupported` while the player renders in software;
-     * `failed` with `failed` when mpv cannot compile a shader (pushed later).
+     * `failed` with `failed` when mpv cannot compile a shader (pushed later;
+     * while other plugins' {@link VideoShaders} are on too, the player
+     * cannot tell whose shader failed and says so in the message).
      */
     readonly status: FilterStatus;
     /**
@@ -6446,6 +6710,152 @@ export interface RenderOptions extends Disposable {
      */
     onStatus(listener: (status: FilterStatus) => void): Disposable;
 }
+/**
+ * This plugin's own GPU shaders, from `plugin.video.shaders(id)`
+ * (`processing.video`, SDK 1.5.39, player 0.5.20): mpv user shaders
+ * (`.glsl`, `//!HOOK` …) that the GPU renderer runs on every frame.
+ *
+ * @remarks
+ * Any number of plugins hold shader handles at the same time (unlike
+ * {@link RenderOptions}, which has one owner). The player joins every
+ * handle's list in a stable order, after the render options' own
+ * `shaders`: built-in plugins first, then installed plugins in the order
+ * they were first installed, then development loads (`--plugin`); ties by
+ * plugin id, and a plugin's handles by `id`. At most 16 shaders across all
+ * handles (`limit` beyond, nothing changes); the render options keep their
+ * own 16.
+ *
+ * Files must be this plugin's own: absolute paths inside its package
+ * directory or {@link Plugin.dataDirectory} after following links, each
+ * at most 16 MiB. Elsewhere: `invalid`; a file that does not exist:
+ * `missing`. The player reads the files when the list is set.
+ *
+ * GPU rendering only (macOS; Windows with Video ▸ GPU Rendering
+ * (Experimental) turned on): under software rendering a non-empty list is
+ * `failed` with `unsupported`, and a switch to software during the run
+ * pushes `unsupported` to every handle with shaders and removes every
+ * list (they no longer count against the 16); set them again once the
+ * player draws on the GPU (after a restart). Shaders act when a
+ * frame is drawn, so processed snapshots and exports never contain them
+ * (use a {@link VideoNode} for that). When mpv cannot compile a shader the
+ * handle turns `failed` with `failed` (pushed later); mpv does not say
+ * which file failed, so while several plugins' shaders are on, each of
+ * them hears it and the message says the player cannot tell whose.
+ *
+ * `set` sends the whole list (last write wins); `clear` and `dispose`
+ * withdraw it; the player removes a stopped plugin's shaders itself.
+ * Players before 0.5.20 refuse the request (the handle is `failed`): declare
+ * `"minPlayerVersion": "0.5.20"`.
+ *
+ * @example Add a sharpening shader the plugin ships
+ * The video looks sharper on the GPU renderer; under software rendering
+ * the OSD says why it is not. The shader file lives in the plugin's
+ * package, and the player puts it after other plugins' shaders that come
+ * earlier in its order.
+ * ```ts
+ * import { join } from "node:path";
+ * declare const packageDirectory: string;
+ * // ---cut---
+ * const shaders = plugin.video.shaders("sharpen");
+ * shaders.onStatus((s) => {
+ *   // `unsupported`: software rendering; `failed`: mpv could not compile it.
+ *   if (s.state === "failed") void plugin.osd.show("Sharpen: {}", [s.error.message]);
+ * });
+ * shaders.set([join(packageDirectory, "shaders", "sharpen.glsl")]);
+ * ```
+ *
+ * @capability processing.video
+ * @player 0.5.20; older players refuse the request.
+ * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @since 1.5.39
+ * @category Processing
+ */
+export interface VideoShaders extends Disposable {
+    /**
+     * Replace this handle's shader list (last write wins); `[]` withdraws
+     * it.
+     *
+     * @remarks
+     * Never throws: a refused list shows in `status` (`invalid`, `missing`,
+     * `limit`, `unsupported`) and goes to {@link Scope.onError}, and what the
+     * player held stays.
+     *
+     * @capability processing.video
+     * @param paths - Absolute paths of shader files in this plugin's package
+     *   or data directory, in the order they run.
+     *
+     * @example Switch between two shader presets
+     * The plugin offers a light and a strong preset; picking one replaces
+     * the handle's list in one request. The files were written to the
+     * plugin's data directory when the user imported them.
+     * ```ts
+     * import { join } from "node:path";
+     * // ---cut---
+     * const presets: Record<string, string[]> = {
+     *   light: [join(plugin.dataDirectory, "denoise.glsl")],
+     *   strong: [join(plugin.dataDirectory, "denoise.glsl"), join(plugin.dataDirectory, "sharpen.glsl")],
+     * };
+     * plugin.video.shaders("presets").set(presets.strong!);
+     * ```
+     *
+     * @since 1.5.39
+     */
+    set(paths: readonly string[]): void;
+    /**
+     * Withdraw this handle's shaders (the same as `set([])`).
+     *
+     * @capability processing.video
+     *
+     * @example Turn the plugin's shaders off from a menu item
+     * A Video menu item turns the plugin's shader on and off. Clearing
+     * keeps the handle, so the next pick sets the list again.
+     * ```ts
+     * declare const file: string;
+     * // ---cut---
+     * const shaders = plugin.video.shaders();
+     * let on = false;
+     * plugin.commands.add({
+     *   id: "toggle-shader",
+     *   path: ["@video", "Sharpen (Shader)"],
+     *   checked: () => on,
+     *   run: () => {
+     *     on = !on;
+     *     // Clearing keeps the handle; the next pick sets the list again.
+     *     if (on) shaders.set([file]);
+     *     else shaders.clear();
+     *   },
+     * });
+     * ```
+     *
+     * @since 1.5.39
+     */
+    clear(): void;
+    /**
+     * Current status: `waiting` before ready media, `applying`, `applied`,
+     * or `failed` with the reason (see the remarks).
+     */
+    readonly status: FilterStatus;
+    /**
+     * The status changed, including later pushes (a compile failure, a
+     * switch to software rendering).
+     *
+     * @capability processing.video
+     *
+     * @example Report a shader that does not compile
+     * The OSD shows mpv's message when the plugin's shader fails to compile.
+     * The player pushes that failure after the list was accepted, so it
+     * arrives through `onStatus`, not as a refused `set`.
+     * ```ts
+     * const shaders = plugin.video.shaders();
+     * shaders.onStatus((status) => {
+     *   if (status.state === "failed") void plugin.osd.show("Shader: {}", [status.error.message]);
+     * });
+     * ```
+     *
+     * @since 1.5.39
+     */
+    onStatus(listener: (status: FilterStatus) => void): Disposable;
+}
 /**
  * Why the GPU's video upscaler does not work, as a stable kebab-case code.
  * A newer player may add codes: compare with the ones you handle and show
@@ -8422,14 +8832,17 @@ export interface Bindings {
      */
     reset(ref?: BindingRef): Promise<void>;
     /**
-     * Declarations or overrides changed (read `list()` again). At most every 200 ms.
+     * The binding list changed (read `list()` again): a declaration or an
+     * override. At most every 200 ms; since player 0.5.21 only when the list
+     * itself changed, not when a plugin starts again with the same commands.
      *
      * @capability bindings.manage
      *
      * @example Refresh a key list when bindings change
      * The plugin's key list stays current when the user changes a key in the
-     * player or another plugin starts. The listener carries no data and runs
-     * at most every 200 ms; the plugin reads the table again with `list`.
+     * player or a plugin with other commands is installed. The listener
+     * carries no data and runs at most every 200 ms; the plugin reads the
+     * table again with `list`.
      * ```ts
      * declare function render(commands: BindingInfo[]): void;
      * // ---cut---
@@ -9295,10 +9708,10 @@ export type RenderingPreference = "auto" | "gpu" | "software";
  *
  * | Code | Meaning |
  * | --- | --- |
- * | `default` | Nothing ruled the GPU out; the platform's default. |
+ * | `default` | Nothing ruled the GPU out; the platform's default (macOS: GPU; Windows since version 0.5.14: software until the user turns on GPU rendering). |
  * | `pending` | GPU rendering is starting. |
  * | `headless` | The player runs without a user interface. |
- * | `no-gpu-backend` | This player has no GPU renderer on this system (Windows today). |
+ * | `no-gpu-backend` | This player has no GPU renderer on this system (Linux today; Windows has one since version 0.5.14, off by default, which reports `default`). |
  * | `env` | The environment chose it (`VESTRA_RENDER`, `VESTRA_SOFTWARE_RENDER`). |
  * | `preference` | The user chose software rendering ({@link Rendering.setPreference}); GPU chosen and available reports `default`. |
  * | `denylist` | The graphics driver is on the player's denylist. |

package/dist/plugin/ui.js

@@ -92,7 +92,8 @@ export class ViewBase {
     scope;
     handlers = new Map();
     #values = new Map();
-    #binders = new Set();
+    /** Each binding, with where the plugin added it (for the player's log). */
+    #binders = new Map();
     /** What the host currently shows, as far as this side knows. */
     #sent = new Map();
     /** Written by `set()`: sent even if equal to what was sent before. */
@@ -144,7 +145,7 @@ export class ViewBase {
         this.flush();
     }
     bind(props) {
-        this.#binders.add(props);
+        this.#binders.set(props, this.scope.runtime.callSite());
         this.scope.update();
         return this.scope.onDispose(() => {
             this.#binders.delete(props);
@@ -152,9 +153,10 @@ export class ViewBase {
     }
     /** Current desired properties (bound values win over earlier `set`). */
     snapshot() {
-        for (const binder of this.#binders) {
+        for (const [binder, site] of this.#binders) {
             try {
-                for (const [key, value] of Object.entries(encode(binder())))
+                const props = this.scope.runtime.reader("a view's bind", site, binder);
+                for (const [key, value] of Object.entries(encode(props)))
                     this.#values.set(key, value);
             }
             catch (error) {

package/dist/plugin/when.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `plugin.when`: conditions on the player's own state that the player
+ * evaluates for a command's `enabled` and `checked` (player 0.5.21). The
+ * wire form is `commands.register` / `commands.update` `when`.
+ */
+import type { Condition, LanguagePreference, PlayerState, ThemeId, When } from "./types.ts";
+/** A condition in the wire form: an object of exactly one key. */
+export type ConditionJson = {
+    phase: PlayerState["phase"][];
+} | {
+    paused: boolean;
+} | {
+    kind: PlayerState["kind"];
+} | {
+    can: keyof PlayerState["can"];
+} | {
+    fullscreen: boolean;
+} | {
+    theme: ThemeId;
+} | {
+    language: LanguagePreference;
+} | {
+    all: ConditionJson[];
+} | {
+    any: ConditionJson[];
+} | {
+    not: ConditionJson;
+};
+/** What conditions read, in the SDK's names. */
+export interface ConditionFacts {
+    phase: PlayerState["phase"];
+    paused: boolean;
+    kind: PlayerState["kind"];
+    can: Readonly<Record<string, boolean>>;
+    fullscreen: boolean;
+    theme: string;
+    language: string;
+}
+/** Whether `value` is a condition made by `plugin.when`. */
+export declare const isCondition: (value: unknown) => value is Condition;
+/** A condition's wire form; throws for anything else. */
+export declare function conditionJson(condition: Condition): ConditionJson;
+/** The one `plugin.when` (conditions hold no plugin state). */
+export declare const WHEN: When;
+/** Evaluate a wire condition as the player does (for the test host). */
+export declare function evaluate(json: ConditionJson, facts: ConditionFacts): boolean;