@vestra-player/sdk 1.5.42 → 1.5.44

package/dist/plugin/testing.js

@@ -86,6 +86,7 @@ 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 { applyOps, PATCH_FEATURE, PATCH_OPS } from "./patch.js";
 import { evaluate } from "./when.js";
 import { WAKE_EVENTS } from "./runtime.js";
 import { THEMES } from "./appearance.js";
@@ -929,6 +930,54 @@ export class TestHost {
         if (reason !== null && reason !== undefined)
             this.#declared(reason, "reason");
     }
+    /**
+     * Row patches (player 0.6.0): the `seq` of each property's last write, by
+     * view and property (none: 0, the initial properties).
+     */
+    #writes = new Map();
+    #resetWrites(view) {
+        for (const slot of [...this.#writes.keys()])
+            if (slot.startsWith(`${view}\u0000`))
+                this.#writes.delete(slot);
+    }
+    /**
+     * A property write as the player takes it, returning the value the
+     * property shows after it: a whole `value`, or a `patch` of the array
+     * `current` applying on the write numbered `base` (code `stale`
+     * otherwise). The result is checked against the value limits whole: the
+     * player counts the rows a patch keeps too.
+     */
+    #write(view, property, p, current) {
+        const slot = `${view}\u0000${property}`;
+        const patch = p.patch;
+        if (patch === undefined) {
+            const value = this.#shownValues(p.value);
+            this.#checkValues({ [property]: value });
+            this.#seeImages([value]);
+            this.#writes.set(slot, typeof p.seq === "number" ? p.seq : 0);
+            return value;
+        }
+        const { base, seq } = patch;
+        if (!Number.isInteger(base) ||
+            !Number.isInteger(seq) ||
+            base < 0 ||
+            seq < 1)
+            throw new HostError("invalid", "patch.base and patch.seq require non-negative integers (seq ≥ 1)");
+        const stale = () => new HostError("stale", "the property changed since the write this patch applies on; send the whole value");
+        if ((this.#writes.get(slot) ?? 0) !== base || !Array.isArray(current))
+            throw stale();
+        const ops = patchOps(patch.ops, current.length);
+        const resolved = ops.map((op) => op.op === "set"
+            ? { ...op, row: this.#shownValues(op.row) }
+            : op.op === "insert"
+                ? { ...op, rows: op.rows.map((row) => this.#shownValues(row)) }
+                : op);
+        const value = applyOps(current, resolved);
+        this.#checkValues({ [property]: value });
+        this.#seeImages(resolved.flatMap((op) => op.op === "set" ? [op.row] : op.op === "insert" ? op.rows : []));
+        this.#writes.set(slot, seq);
+        return value;
+    }
     /**
      * Refuse property values over the player's limits ({@link UI_VALUE_LIMITS})
      * with `limit`, naming the property, as the player does.
@@ -1837,7 +1886,104 @@ export class TestHost {
         factor: 2,
         checked: false,
         renderingStarting: false,
+        video: {
+            width: 1920,
+            height: 1080,
+            displayWidth: 1920,
+            displayHeight: 1080,
+        },
+        area: { width: 3840, height: 2160 },
+        gpu: "NVIDIA GeForce RTX 4070 Laptop GPU",
+        hwdecCurrent: "d3d11va",
     };
+    /**
+     * Make the upscaler's reason `decoding` with `cause`, with the player's
+     * message (player 0.5.25), and set `upscaling.hwdecCurrent` to match
+     * (`d3d11va-copy`, `no`, `nvdec`). `plugins` are named for `copy-back`
+     * only, as the player does. Returns the reason; call
+     * {@link TestHost.upscalingChanged} to tell a listening plugin.
+     *
+     * @example Test the window's advice for each cause
+     * The plugin's window explains why upscaling waits. The test fakes the
+     * copy-back cause that Picture Adjustments' filters cause and checks
+     * that the window names the plugin.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscalingDecoding("copy-back", [{ id: "vestra.video", name: "Picture Adjustments" }]);
+     * host.upscalingChanged();
+     * await host.settle();
+     * assert.match(String(host.window("upscale").props.blocker), /Picture Adjustments/);
+     * ```
+     *
+     * @capability None.
+     * @since 1.5.43
+     */
+    upscalingDecoding(cause, plugins = []) {
+        const needs = "upscaling needs it decoded on the GPU that renders it (d3d11va)";
+        const names = plugins.map((p) => p.name);
+        const because = names.length === 0
+            ? "for example because a video filter needs the frames in memory"
+            : names.length === 1
+                ? `because the video filter of ${names[0]} needs the frames in memory`
+                : `because the video filters of ${names.join(", ")} need the frames in memory`;
+        const [message, current] = cause === "copy-back"
+            ? [
+                `the video is decoded with copy-back (auto-copy-safe), ${because}; ${needs}`,
+                "d3d11va-copy",
+            ]
+            : cause === "hwdec-off"
+                ? [
+                    "hardware decoding is off; upscaling needs the video decoded on the GPU that renders it (d3d11va)",
+                    "no",
+                ]
+                : cause === "software"
+                    ? [`this video is decoded in software; ${needs}`, "no"]
+                    : [`this video is decoded with nvdec; ${needs}`, "nvdec"];
+        const reason = cause === "copy-back"
+            ? {
+                code: "decoding",
+                message,
+                cause,
+                plugins: plugins.map(({ id, name }) => ({ id, name })),
+            }
+            : { code: "decoding", message, cause };
+        this.upscaling.reason = reason;
+        this.upscaling.hwdecCurrent = current;
+        return reason;
+    }
+    /**
+     * Send `video.upscaling.changed` with the state {@link TestHost.upscaling}
+     * describes now (without `enabled`), as the player does when it changes
+     * (player 0.5.25); a plugin listening with
+     * `plugin.video.upscaling.onChange` receives it. Nothing reaches a plugin
+     * that does not listen.
+     *
+     * @capability None.
+     *
+     * @example Show the new factor in the plugin's window
+     * The window resized: the test changes the area and the factor, sends
+     * the change, and checks that the plugin's window shows the new factor.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscaling.area = { width: 2560, height: 1440 };
+     * host.upscaling.factor = 1.33; // 1080p in a 1440p area
+     * host.upscalingChanged(); // as the player after the resize settled
+     * await host.settle();
+     * assert.equal(host.window("upscale").props.factor, "×1.33");
+     * ```
+     *
+     * @since 1.5.43
+     */
+    upscalingChanged() {
+        if (!this.subscriptions.has("video.upscaling.changed"))
+            return;
+        const { enabled: _, ...state } = this.#upscalingState(false);
+        this.emit("video.upscaling.changed", state);
+    }
     /** What `player.chapters()` lists while media is ready. */
     chapters = [];
     #overrides = new Map();
@@ -3481,12 +3627,20 @@ export class TestHost {
                 message: "the player has not checked the GPU yet; state() or set(true) checks it",
             };
         const requested = enabled && reason === null && factor !== null && factor > 1;
+        const { video, area, gpu, hwdecCurrent } = this.upscaling;
         return {
             available: reason === null,
-            reason: reason ? { ...reason } : null,
+            reason: reason
+                ? structuredClone(reason)
+                : null,
             enabled,
             requested,
             factor: requested ? factor : null,
+            video: video ? { ...video } : null,
+            area: area ? { ...area } : null,
+            gpu,
+            hwdecCurrent,
+            inChain: requested,
         };
     }
     /** `rendering.state` from {@link TestHost.rendering} and `videoRender.gpu`. */
@@ -3711,6 +3865,7 @@ export class TestHost {
             const id = String(p.id);
             if (this.windows.has(id))
                 throw new HostError("conflict", "view already exists");
+            this.#resetWrites(`w:${id}`);
             const properties = this.#shownValues(p.properties);
             this.#checkValues(properties);
             this.#seeImages(properties);
@@ -3736,10 +3891,8 @@ export class TestHost {
             const window = this.windows.get(String(p.id));
             if (!window)
                 throw new HostError("missing", "view not found");
-            const value = this.#shownValues(p.value);
-            this.#checkValues({ [String(p.property)]: value });
-            this.#seeImages([value]);
-            window.props[String(p.property)] = value;
+            const property = String(p.property);
+            window.props[property] = this.#write(`w:${String(p.id)}`, property, p, window.props[property]);
         },
         "ui.show": (p) => {
             const window = this.windows.get(String(p.id));
@@ -3773,6 +3926,7 @@ export class TestHost {
                 ]));
             const properties = this.#initialValues(this.#shownValues(p.properties));
             this.#seeImages(properties);
+            this.#resetWrites("$mount");
             const host = this;
             this.panel = {
                 slot: String(p.slot),
@@ -4097,11 +4251,9 @@ export class TestHost {
             this.emit("sequence.step", { direction });
         },
         "ui.setMount": (p) => {
-            this.mounted();
-            const value = this.#shownValues(p.value);
-            this.#checkValues({ [String(p.property)]: value });
-            this.#seeImages([value]);
-            this.mounted().props[String(p.property)] = value;
+            const panel = this.mounted();
+            const property = String(p.property);
+            panel.props[property] = this.#write("$mount", property, p, panel.props[property]);
         },
         "timeline.marks": () => ({ marks: this.timeline.marks }),
         "drops.provide": (p) => {
@@ -4140,6 +4292,7 @@ export class TestHost {
                 throw new HostError("invalid", "a plugin has at most 8 settings pages");
             const properties = this.#initialValues(this.#shownValues(p.properties));
             this.#seeImages(properties);
+            this.#resetWrites(`$settings:${id}`);
             const host = this;
             this.settings.pages.set(id, {
                 category: String(p.category),
@@ -4162,10 +4315,8 @@ export class TestHost {
             const page = this.settings.pages.get(String(p.id));
             if (!page)
                 throw new HostError("missing", "page not registered");
-            const value = this.#shownValues(p.value);
-            this.#checkValues({ [String(p.property)]: value });
-            this.#seeImages([value]);
-            page.props[String(p.property)] = value;
+            const property = String(p.property);
+            page.props[property] = this.#write(`$settings:${String(p.id)}`, property, p, page.props[property]);
         },
         "settings.unregister": (p) => {
             this.settings.pages.delete(String(p.id));
@@ -5156,7 +5307,10 @@ export async function startPlugin(activate, options = {}) {
     mkdirSync(data, { recursive: true });
     if (host.fileRoots.length === 0)
         host.fileRoots = [directory, data];
-    const instance = await createPlugin(host, manifest, directory, data, host.app);
+    const instance = await createPlugin(host, manifest, directory, data, 
+    // Like the player: protocol additions it takes (`app.features` set on
+    // the host replaces them, e.g. `[]` for an older player's behaviour).
+    { features: [PATCH_FEATURE], ...host.app });
     await activate(instance.plugin);
     // Like the player: a position or resolver another plugin holds is not an
     // activation failure.
@@ -5185,3 +5339,72 @@ export async function startPlugin(activate, options = {}) {
         },
     };
 }
+/**
+ * A patch's ops checked against an array of `length` rows, as the player
+ * checks them (`ui_patch.rs`): in order, each on the result of the ones
+ * before; at most {@link PATCH_OPS}; the result at most
+ * `UI_VALUE_LIMITS.arrayRows` rows.
+ */
+function patchOps(ops, length) {
+    if (!Array.isArray(ops))
+        throw new HostError("invalid", "patch.ops requires an array");
+    if (ops.length > PATCH_OPS)
+        throw new HostError("limit", `a patch carries at most ${PATCH_OPS} operations`);
+    const index = (op, key) => {
+        const value = op[key];
+        if (!Number.isInteger(value) || value < 0)
+            throw new HostError("invalid", `patch op ${key} requires a non-negative integer`);
+        return value;
+    };
+    const count = (op) => {
+        const value = index(op, "count");
+        if (value === 0)
+            throw new HostError("invalid", "patch op count must be at least 1");
+        return value;
+    };
+    const past = (what) => new HostError("invalid", `${what} is past the end of the list`);
+    let len = length;
+    return ops.map((raw) => {
+        const op = (raw ?? {});
+        switch (op.op) {
+            case "set": {
+                const at = index(op, "at");
+                if (at >= len)
+                    throw past(`set at ${at}`);
+                if (!("row" in op))
+                    throw new HostError("invalid", "patch op set requires row");
+                return { op: "set", at, row: op.row };
+            }
+            case "insert": {
+                const at = index(op, "at");
+                const rows = op.rows;
+                if (!Array.isArray(rows) || rows.length === 0)
+                    throw new HostError("invalid", "patch op insert requires rows");
+                if (at > len)
+                    throw past(`insert at ${at}`);
+                len += rows.length;
+                if (len > UI_VALUE_LIMITS.arrayRows)
+                    throw new HostError("limit", `UI array exceeds ${UI_VALUE_LIMITS.arrayRows} rows`);
+                return { op: "insert", at, rows: rows };
+            }
+            case "remove": {
+                const at = index(op, "at");
+                const n = count(op);
+                if (at + n > len)
+                    throw past(`remove ${n} at ${at}`);
+                len -= n;
+                return { op: "remove", at, count: n };
+            }
+            case "move": {
+                const from = index(op, "from");
+                const n = count(op);
+                const to = index(op, "to");
+                if (from + n > len || to + n > len)
+                    throw past(`move ${n} from ${from} to ${to}`);
+                return { op: "move", from, count: n, to };
+            }
+            default:
+                throw new HostError("invalid", "patch op must be set, insert, remove or move");
+        }
+    });
+}

package/dist/plugin/types.d.ts

@@ -6870,7 +6870,7 @@ export interface VideoShaders extends Disposable {
  * | `gpu-unsupported` | The driver does not offer upscaling on this GPU (Windows: not an RTX GPU), or the check failed. |
  * | `rendering` | The player renders in software, or GPU rendering is still starting; upscaling needs GPU rendering ({@link Rendering}). |
  * | `adapter` | GPU rendering runs on another GPU than the one that can upscale (a laptop with two GPUs; Windows: choose the high-performance GPU for Vestra in Settings ▸ System ▸ Display ▸ Graphics). |
- * | `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a {@link VideoFilter} needs the frames in memory. |
+ * | `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a {@link VideoFilter} needs the frames in memory. {@link UpscalingReason.cause} says which, and {@link UpscalingReason.plugins} whose filters (newer players; see there). |
  * | `unchecked` | The player has not checked the GPU yet. Only in the answer to `set(false)`, which never starts the check; `state()` and `set(true)` always check first. |
  *
  * `decoding` and `rendering` while GPU rendering is still starting can pass
@@ -6925,6 +6925,93 @@ export interface UpscalingReason {
      * and what to change; never branch on it.
      */
     readonly message: string;
+    /**
+     * With code `decoding` only: why the video is not decoded on the GPU
+     * that renders it ({@link UpscalingDecodingCause}). Absent with every
+     * other code, and from players before 0.5.25.
+     *
+     * @player 0.5.25; older players send `decoding` without a cause.
+     * @since 1.5.43
+     */
+    readonly cause?: UpscalingDecodingCause;
+    /**
+     * With cause `copy-back` only: the plugins whose video filters need the
+     * frames in memory, which is why the player switched to copy-back
+     * decoding, in the order the plugins started (each plugin once). Name
+     * them to the user, who can turn the filters off there. Empty when
+     * the copy-back decoding is not one the player chose for a filter (the
+     * user's own `hwdec` setting). Absent with any other cause, and from
+     * players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly plugins?: readonly UpscalingPlugin[];
+}
+/**
+ * Why the video is not decoded on the GPU that renders it: the
+ * {@link UpscalingReason.cause} of a `decoding` reason (player 0.5.25). A
+ * newer player may add causes: show {@link UpscalingReason.message} for the
+ * ones you do not handle.
+ *
+ * | Cause | Meaning |
+ * | --- | --- |
+ * | `copy-back` | Decoded on the GPU and copied back to memory, because a plugin's video filter needs the frames there ({@link UpscalingReason.plugins} names it), or because of the user's `hwdec` setting. |
+ * | `hwdec-off` | Hardware decoding is turned off (mpv's `hwdec` is `no`). |
+ * | `software` | This video is decoded in software: a cover picture, a format the GPU does not decode, or a hardware decoder that failed. It passes with the next video. |
+ * | `other-hwdec` | This video is decoded with another hardware decoder than the one the upscaler needs. |
+ *
+ * @example Name the plugins whose filters block upscaling
+ * A plugin's upscaling window explains a `decoding` reason by its cause,
+ * and for `copy-back` names the plugins whose filters stand in the way, so
+ * the user can turn them off there (a plugin cannot run another plugin's
+ * commands).
+ * ```ts
+ * const { reason } = await plugin.video.upscaling.state();
+ * if (reason?.code === "decoding" && reason.cause === "copy-back") {
+ *   const names = (reason.plugins ?? []).map((p) => p.name).join(", ");
+ *   // Ask the user to reset those filters; the manifest names are not translated.
+ *   console.log(names ? `Turn off the video filters of ${names}` : reason.message);
+ * } else if (reason) console.log(reason.message);
+ * ```
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export type UpscalingDecodingCause = "copy-back" | "hwdec-off" | "software" | "other-hwdec" | (string & {});
+/**
+ * A plugin named in an {@link UpscalingReason}: its manifest id and its
+ * name for people, as its manifest gives it (not translated).
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export interface UpscalingPlugin {
+    /** The plugin's manifest id, for example `vestra.video`. */
+    readonly id: string;
+    /** The manifest's `name` as is (its id without one), for people. */
+    readonly name: string;
+}
+/**
+ * The video's size as the upscaler gets it ({@link UpscalingState.video}):
+ * the decoder's frame size, width and height swapped for the file's
+ * quarter-turn rotation metadata.
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export interface UpscalingVideoSize {
+    /** The frames' stored width in pixels. */
+    readonly width: number;
+    /** The frames' stored height in pixels. */
+    readonly height: number;
+    /** The width the video is meant to be shown at (non-square pixels). */
+    readonly displayWidth: number;
+    /** The height the video is meant to be shown at. */
+    readonly displayHeight: number;
 }
 /**
  * What {@link VideoUpscaling.state} and {@link VideoUpscaling.set} report:
@@ -6980,6 +7067,59 @@ export interface UpscalingState {
      * nothing is requested.
      */
     readonly factor: number | null;
+    /**
+     * The video's size as the upscaler gets it; `null` while no video
+     * decodes. With {@link UpscalingState.area} it explains the factor.
+     * Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly video?: UpscalingVideoSize | null;
+    /**
+     * The area the video is shown in, in pixels (the upscaler scales the
+     * video to fit it); `null` while the player shows no video area. Absent
+     * from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly area?: {
+        /** Width in physical pixels. */
+        readonly width: number;
+        /** Height in physical pixels. */
+        readonly height: number;
+    } | null;
+    /**
+     * The name of the GPU that renders, for example `NVIDIA GeForce RTX 4070
+     * Laptop GPU`; `null` in software rendering and where the player does not
+     * know it (macOS, Linux). Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly gpu?: string | null;
+    /**
+     * The hardware decoder in use for this video, as mpv names it (`d3d11va`,
+     * `d3d11va-copy`; `no` for software decoding); `null` while no video
+     * decodes. For people and logs: branch on {@link UpscalingReason.cause}.
+     * Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly hwdecCurrent?: string | null;
+    /**
+     * The upscaler is in the player's video filter chain now, read from the
+     * chain itself (`requested` is what the player asked for; they differ
+     * only for a moment, while the chain changes). Still not a sign that the
+     * GPU upscales: the driver gives none (see the remarks). Absent from
+     * players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly inChain?: boolean;
 }
 /**
  * `plugin.video.upscaling`: the GPU's video upscaler, NVIDIA RTX Video
@@ -7119,6 +7259,57 @@ export interface VideoUpscaling {
      * @since 1.5.37
      */
     set(enabled: boolean): Promise<UpscalingState>;
+    /**
+     * Call `listener` with the new state whenever it changes while some
+     * plugin has upscaling on: the factor, whether the upscaler is in the
+     * chain, the reason, the video's and the area's size, the decoder. A
+     * window that shows how upscaling runs listens instead of polling
+     * {@link VideoUpscaling.state}.
+     *
+     * @remarks
+     * The player looks about five times a second while upscaling is on for
+     * any plugin (a window resize sends at most that many), and sends a
+     * change only when something differs; after the last plugin turns it
+     * off one more change says so, then nothing until it is on again: read
+     * {@link VideoUpscaling.state} when you need the state then. Nothing is
+     * sent before the player's GPU check ran (the first `state()` or
+     * `set(true)` of any plugin). `enabled` is this plugin's own request, as
+     * in `state()`. The message of a `rendering` reason can be shorter than
+     * the one `state()` gives (it may leave out what to do).
+     *
+     * **A listener keeps the plugin running.** `video.upscaling.changed` is
+     * not an event the player wakes a stopped plugin for: while the plugin
+     * listens, the player does not stop it while idle (lazy activation), even
+     * with upscaling off. Listen only while a window that shows the state is
+     * open, and dispose of the listener when it closes. Players before 0.5.25 do not know the event: the listener
+     * never fires and the SDK logs that the player refused the subscription.
+     *
+     * @capability video.upscaling
+     * @param listener - Receives the new state.
+     * @returns Stops listening; also when the scope that added it is
+     *   disposed.
+     * @throws `capability` (synchronously) The manifest does not declare
+     *   `video.upscaling`.
+     *
+     * @example Show how upscaling runs while a window is open
+     * The plugin's window shows the factor, the sizes and the GPU while it
+     * is open; the listener goes when the window closes, so the plugin can
+     * be stopped while idle again.
+     * ```ts
+     * // When the window opens:
+     * const watch = plugin.video.upscaling.onChange((state) => {
+     *   const video = state.video ? `${state.video.width}×${state.video.height}` : "no video";
+     *   const area = state.area ? `${state.area.width}×${state.area.height}` : "—";
+     *   console.log(`${video} → ${area}, ×${state.factor ?? 1}, ${state.gpu ?? "no GPU"}`);
+     * });
+     * // When it closes: stop listening (it keeps the plugin running).
+     * await watch.dispose();
+     * ```
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    onChange(listener: (state: UpscalingState) => void): Disposable;
 }
 /**
  * A subtitle track of the current source.

package/dist/plugin/ui.d.ts

@@ -1,4 +1,4 @@
-import type { Json } from "../wire.ts";
+import type { Json, PropertyWrite } from "../wire.ts";
 import type { ScopeImpl } from "./scope.ts";
 import type { Dialogs, Disposable, ImageOptions, ImageRef, Panels, PropValue, Props, Ui, View, Windows } from "./types.ts";
 /** Slint names are kebab-case; plugin code may use camelCase. */
@@ -29,7 +29,7 @@ export declare abstract class ViewBase implements View {
     protected closed: boolean;
     constructor(scope: ScopeImpl);
     protected abstract live(): boolean;
-    protected abstract write(property: string, value: Json): Promise<void>;
+    protected abstract write(property: string, write: PropertyWrite): Promise<void>;
     /**
      * Initial properties in wire form. A released image is left out (the
      * property keeps its default) and reported, like a failed write.