@vestra-player/sdk 1.5.43 → 1.5.45

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.
@@ -3164,6 +3213,13 @@ export class TestHost {
      * for: on a loaded machine it can finish after `settle()` returns. Poll
      * the result you assert on instead (second example).
      *
+     * `settle()` does not wait for the SDK's once-a-second full update pass
+     * (SDK 1.5.45). After `setSource` (or another player state change) only
+     * the bindings that read a changed field of `plugin.player.state` run
+     * again; state the plugin changed outside a handler without
+     * `plugin.update()` shows only in the next full pass. Have the plugin
+     * call `plugin.update()` after such a change, or wait `settle(1000)`.
+     *
      * @param ms - Extra time to wait, for debounces and timers (default 0).
      *
      * @example Wait past a debounced save
@@ -3816,6 +3872,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);
@@ -3841,10 +3898,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));
@@ -3878,6 +3933,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),
@@ -4202,11 +4258,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) => {
@@ -4245,6 +4299,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),
@@ -4267,10 +4322,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));
@@ -5261,7 +5314,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.
@@ -5290,3 +5346,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

@@ -565,14 +565,16 @@ export interface CommandState {
     reason: TextValue | null;
 }
 /**
- * A value, or a function the SDK re-evaluates on every update pass (see
- * {@link Scope.update}); only changes are sent to the player.
+ * A value, or a function the SDK re-evaluates on every full update pass,
+ * and after a player state change only if it read a field of
+ * `plugin.player.state` that changed (see {@link Scope.update}); only
+ * changes are sent to the player.
  *
  * @example Mix a computed state with a fixed one
  * The Loop item carries a check mark while a loop is set and is always
- * enabled. A function is evaluated again in every update pass (after each
- * handler and player state change) and only changes are sent; a plain
- * value never changes.
+ * enabled. A function is evaluated again in every full update pass (after
+ * each handler), and after a player state change only if it read a changed
+ * field; only changes are sent, and a plain value never changes.
  * ```ts
  * plugin.commands.add({
  *   id: "loop",
@@ -1060,8 +1062,9 @@ export interface CommandOptions {
  * @remarks
  * The handle of one menu item and its keys. Its state (`enabled`, `checked`,
  * `busy`, `reason`) is bound: functions given to {@link Commands.add} or
- * {@link Command.set} are evaluated again in every update pass and only
- * changes reach the player. Its title, path, bindings and button cannot
+ * {@link Command.set} are evaluated again in every full update pass (after
+ * a player state change only if they read a changed field of
+ * `plugin.player.state`) and only changes reach the player. Its title, path, bindings and button cannot
  * change in place; dispose the command (or a child {@link Scope}) and add it
  * again. Disposing it, its scope or stopping the plugin removes the menu
  * item, its keys and its bar button.
@@ -1081,7 +1084,7 @@ export interface CommandOptions {
  *   path: ["@video", "Export…"],
  *   run: runExport,
  * });
- * // A function: re-evaluated in every update pass.
+ * // A function: re-evaluated in every full pass and when `phase` changes.
  * exportCommand.set({ enabled: () => plugin.player.state.phase === "ready" });
  * ```
  *
@@ -1706,8 +1709,9 @@ export interface Ui {
  * callback.
  *
  * `bind` is the usual way: the SDK re-evaluates bound functions in every
- * update pass (after each handler it calls, after player state changes, on
- * {@link Scope.update}) and sends only what changed, at most one write in
+ * full update pass (after each handler it calls, on {@link Scope.update}),
+ * and after a player state change those that read a changed field of
+ * `plugin.player.state`, and sends only what changed, at most one write in
  * flight per view. `set` sends now, even an unchanged value.
  *
  * Writes that fail (a name the Slint file does not declare, a value of the
@@ -1843,7 +1847,11 @@ export interface View {
      *
      * @remarks
      * The SDK calls `props` in every update pass (and right after `bind`) and
-     * sends the values that differ from the ones it sent last. Because an
+     * sends the values that differ from the ones it sent last. After a change
+     * of the player state alone it calls `props` only if it read a field of
+     * `plugin.player.state` that changed (SDK 1.5.45); a full pass follows
+     * after each handler, on {@link Scope.update} and at least once a second
+     * while the player state keeps changing. Because an
      * unchanged value is not sent again, text the user typed into an `in-out`
      * property stays until the plugin's value for it changes.
      *
@@ -1864,8 +1872,9 @@ export interface View {
      * @example Show what is playing and whether it can seek
      * The status window always shows the current file and enables its seek
      * controls only for seekable sources. The SDK calls the function right
-     * away and again in every update pass (after player state changes and
-     * after each handler) and sends only the values that changed.
+     * away, again in every full update pass (after each handler) and after
+     * each change of `source` or `can`, and sends only the values that
+     * changed.
      * ```ts
      * const status = plugin.windows.create("ui/status.slint");
      * status.bind(() => ({
@@ -5697,8 +5706,8 @@ export interface Player {
      * @example Drive the player's Next and Previous from a playlist
      * The player's Next and Previous items and keys play the plugin's list.
      * The player calls `next` and `previous` when the user asks; `canNext`
-     * and `canPrevious` are evaluated again after every handler the SDK runs,
-     * and while they return false the player disables its items ("No next
+     * and `canPrevious` are evaluated again after every handler the SDK runs
+     * (and after a player state change if they read a changed field), and while they return false the player disables its items ("No next
      * item").
      * ```ts
      * declare const items: string[];

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.
@@ -38,7 +38,11 @@ export declare abstract class ViewBase implements View {
     on<A extends Json[]>(callback: string, handler: (...args: A) => unknown): Disposable;
     set(props: Props): void;
     bind(props: () => Props): Disposable;
-    /** Current desired properties (bound values win over earlier `set`). */
+    /**
+     * Current desired properties (bound values win over earlier `set`). A
+     * precise pass (`Runtime.part`) skips a bind function that read none of
+     * the changed state: its last values stay.
+     */
     protected snapshot(): Record<string, PropValue>;
     protected evaluate(): void;
     /** The host already shows these values (e.g. sent as initial properties). */