@vestra-player/sdk 1.5.43 → 1.5.45

package/dist/plugin/ui.js

@@ -6,6 +6,8 @@ import { basename, extname, resolve } from "node:path";
 import { failure, Latest, quiet } from "./runtime.js";
 import { dropsOf } from "./drops.js";
 import { MarkdownHandle, markdown, remoteImageFile } from "./markdown.js";
+import { HostError } from "../wire.js";
+import { countRow, diff, keyOf, PATCH_FEATURE, replay, withinLimits, } from "./patch.js";
 /** Slint names are kebab-case; plugin code may use camelCase. */
 export const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
 const encode = (props) => Object.fromEntries(Object.entries(props).map(([k, v]) => [kebab(k), v]));
@@ -62,8 +64,9 @@ function wireValue(value) {
             throw failure("invalid", `image ${value.path} was released with the scope that created it`);
         return value.toJSON();
     }
+    // Array.from: a hole is `null`, as `JSON.stringify` writes it.
     if (Array.isArray(value))
-        return value.map((item) => wireValue(item));
+        return Array.from(value, (item) => wireValue(item ?? null));
     if (value !== null && typeof value === "object") {
         const out = {};
         for (const [key, item] of Object.entries(value))
@@ -72,6 +75,89 @@ function wireValue(value) {
     }
     return value;
 }
+/** Scalars compared by value. Non-finite numbers are JSON `null`: compared as JSON. */
+const isPrimitive = (value) => value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+/** A row as `JSON.stringify` writes it inside an array. */
+const encodeRow = (row) => JSON.stringify(row) ?? "null";
+/** Each row of an array as `JSON.stringify` writes it; a hole is `null`. */
+const encodeRows = (rows) => Array.from(rows, encodeRow);
+function sameRows(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/** An initial property (wire form) as sent. */
+function sentOf(value, patches) {
+    if (isPrimitive(value))
+        return { kind: "value", value };
+    if (Array.isArray(value) && patches) {
+        const keyed = keyOf(value);
+        return {
+            kind: "rows",
+            rows: {
+                enc: encodeRows(value),
+                field: keyed?.field ?? null,
+                keys: keyed?.keys ?? null,
+                counts: [],
+            },
+        };
+    }
+    return { kind: "json", enc: JSON.stringify(value) };
+}
+/**
+ * The row patch from `sent` to `next` (the bound `rows`), in wire form, and
+ * the new rows' limit counts; `null` when the whole value is to be sent:
+ * nothing to type the rows by (no rows sent), a Markdown document in a row
+ * (the player merges documents in place), too many operations, a value over
+ * the limits (the player refuses it whole, as before), or no change (an
+ * explicit `set()` of the same value).
+ */
+function rowPatch(sent, next, rows) {
+    if (sent.enc.length === 0)
+        return null;
+    if (next.enc.some((row) => row.includes('"$vestraMarkdown"')))
+        return null;
+    const nextKeyed = sent.field === null ? null : next.keyed();
+    const keyed = nextKeyed !== null && nextKeyed.field === sent.field;
+    const plan = diff({ enc: sent.enc, keys: keyed ? sent.keys : null }, { enc: next.enc, keys: keyed ? nextKeyed.keys : null });
+    if (!plan || plan.ops.length === 0)
+        return null;
+    // A released image is refused wherever it is, as in a whole write: the
+    // rows the patch does not carry are checked too (those holding images).
+    for (let j = 0; j < rows.length; j++)
+        if (plan.from[j] >= 0 && next.enc[j].includes('"$vestraImage"'))
+            wireValue(rows[j] ?? null);
+    const counts = next.enc.map((_, j) => {
+        const from = plan.from[j];
+        return (from >= 0 ? sent.counts[from] : undefined) ?? countRow(rows[j]);
+    });
+    if (!withinLimits(counts))
+        return null;
+    // The ops must give exactly the new rows (a guard against this diff's bugs).
+    if (!sameRows(replay(sent.enc, plan.ops, next.enc), next.enc))
+        return null;
+    const ops = plan.ops.map((op) => {
+        switch (op.op) {
+            case "set":
+                return { op: "set", at: op.at, row: wireValue(rows[op.row] ?? null) };
+            case "insert":
+                return {
+                    op: "insert",
+                    at: op.at,
+                    rows: op.rows.map((j) => wireValue(rows[j] ?? null)),
+                };
+            default:
+                return op;
+        }
+    });
+    return { ops, counts };
+}
 export const ui = (scope) => ({
     image(path, options) {
         if (typeof path !== "string" || !path)
@@ -96,6 +182,18 @@ export class ViewBase {
     #binders = new Map();
     /** What the host currently shows, as far as this side knows. */
     #sent = new Map();
+    /**
+     * Row patches (player feature `ui.patch`): each property's last write the
+     * player confirmed, by `seq` (0: the initial properties). A patch applies
+     * on it; a property without one is sent whole.
+     */
+    #bases = new Map();
+    /**
+     * Patches of a property answered `stale` in a row: after two, the
+     * property is sent whole until the view shows its initial properties again.
+     */
+    #stales = new Map();
+    #seq = 0;
     /** Written by `set()`: sent even if equal to what was sent before. */
     #forced = new Set();
     /** The last value of each property whose write failed; not retried until it changes. */
@@ -111,6 +209,10 @@ export class ViewBase {
         this.scope = scope;
         this.#binding = scope.runtime.bind(() => this.evaluate());
     }
+    /** The player takes row patches (and `seq` on whole writes). */
+    get #patches() {
+        return this.scope.runtime.features.has(PATCH_FEATURE);
+    }
     /**
      * Initial properties in wire form. A released image is left out (the
      * property keeps its default) and reported, like a failed write.
@@ -145,18 +247,32 @@ export class ViewBase {
         this.flush();
     }
     bind(props) {
-        this.#binders.set(props, this.scope.runtime.callSite());
+        // `token` names this binding of this view in the runtime's read
+        // tracking: the same function bound to two views is two parts.
+        this.#binders.set(props, {
+            site: this.scope.runtime.callSite(),
+            token: {},
+        });
         this.scope.update();
         return this.scope.onDispose(() => {
             this.#binders.delete(props);
         });
     }
-    /** 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.
+     */
     snapshot() {
-        for (const [binder, site] of this.#binders) {
+        const runtime = this.scope.runtime;
+        for (const [binder, { site, token }] of this.#binders) {
             try {
-                const props = this.scope.runtime.reader("a view's bind", site, binder);
-                for (const [key, value] of Object.entries(encode(props)))
+                // Encoded inside the part: what encoding reads counts as the
+                // function's (a state object it returned).
+                const result = runtime.part(token, () => encode(runtime.reader("a view's bind", site, binder)));
+                if (!result)
+                    continue;
+                for (const [key, value] of Object.entries(result.value))
                     this.#values.set(key, value);
             }
             catch (error) {
@@ -173,11 +289,107 @@ export class ViewBase {
     }
     /** The host already shows these values (e.g. sent as initial properties). */
     shown(values) {
-        this.#sent = new Map(Object.entries(values).map(([k, v]) => [k, JSON.stringify(v)]));
+        const patches = this.#patches;
+        this.#sent = new Map(Object.entries(values).map(([k, v]) => [k, sentOf(v, patches)]));
+        this.#bases = new Map(patches ? Object.keys(values).map((key) => [key, 0]) : []);
+        this.#stales.clear();
         this.#forced.clear();
         for (const key of Object.keys(values))
             this.#failed.delete(key);
     }
+    /** `value` encoded, and whether it differs from what was sent. */
+    #encode(key, value) {
+        const sent = this.#sent.get(key);
+        if (isPrimitive(value)) {
+            // Compared as it is: no `JSON.stringify` for the scalars of a pass.
+            const changed = sent?.kind === "value"
+                ? sent.value !== value
+                : sent?.kind !== "json" || sent.enc !== JSON.stringify(value);
+            return {
+                key,
+                value,
+                changed,
+                signature: () => JSON.stringify(value),
+                sent: () => ({ kind: "value", value }),
+            };
+        }
+        if (Array.isArray(value) && this.#patches) {
+            // Row by row: the same work as one `JSON.stringify`, and the rows to
+            // diff against those last sent.
+            const enc = encodeRows(value);
+            const signature = () => `[${enc.join(",")}]`;
+            const changed = sent?.kind === "rows"
+                ? !sameRows(sent.rows.enc, enc)
+                : sent?.kind !== "json" || sent.enc !== signature();
+            // Keys only for a write: an unchanged array costs its encoding alone.
+            let keys;
+            const keyed = () => (keys === undefined ? (keys = keyOf(value)) : keys);
+            return {
+                key,
+                value,
+                changed,
+                signature,
+                rows: { enc, keyed },
+                sent: (counts = []) => ({
+                    kind: "rows",
+                    rows: {
+                        enc,
+                        field: keyed()?.field ?? null,
+                        keys: keyed()?.keys ?? null,
+                        counts,
+                    },
+                }),
+            };
+        }
+        const enc = JSON.stringify(value);
+        return {
+            key,
+            value,
+            changed: sent?.kind !== "json" || sent.enc !== enc,
+            signature: () => enc,
+            sent: () => ({ kind: "json", enc }),
+        };
+    }
+    /**
+     * Write one property: a row patch when the player takes them and one
+     * applies (else the whole value); a `stale` patch is followed by the whole
+     * value at once. The base is forgotten on any failure, so the next write
+     * of the property is whole.
+     */
+    async #send(pending) {
+        const { key, value } = pending;
+        if (!this.#patches) {
+            await this.write(key, { value: wireValue(value) });
+            return pending.sent();
+        }
+        const base = this.#bases.get(key);
+        this.#bases.delete(key);
+        const sent = this.#sent.get(key);
+        const plan = base !== undefined &&
+            sent?.kind === "rows" &&
+            pending.rows &&
+            (this.#stales.get(key) ?? 0) < 2
+            ? rowPatch(sent.rows, pending.rows, value)
+            : null;
+        if (plan) {
+            const seq = ++this.#seq;
+            try {
+                await this.write(key, { patch: { base: base, seq, ops: plan.ops } });
+                this.#bases.set(key, seq);
+                this.#stales.delete(key);
+                return pending.sent(plan.counts);
+            }
+            catch (error) {
+                if (!(error instanceof HostError && error.code === "stale"))
+                    throw error;
+                this.#stales.set(key, (this.#stales.get(key) ?? 0) + 1);
+            }
+        }
+        const seq = ++this.#seq;
+        await this.write(key, { value: wireValue(value), seq });
+        this.#bases.set(key, seq);
+        return pending.sent();
+    }
     /**
      * Send what changed. A bound value is sent when it differs from the last one
      * sent; a `set()` value is always sent once. Nothing is resent merely
@@ -198,20 +410,22 @@ export class ViewBase {
             try {
                 let pending;
                 do {
-                    pending = [...this.#values].filter(([key, value]) => {
-                        const encoded = JSON.stringify(value);
-                        if (this.#failed.get(key) === encoded)
-                            return false;
-                        return this.#forced.has(key) || this.#sent.get(key) !== encoded;
-                    });
-                    for (const [key, value] of pending) {
+                    pending = [];
+                    for (const [key, value] of this.#values) {
+                        const encoded = this.#encode(key, value);
+                        const failedAs = this.#failed.get(key);
+                        if (failedAs !== undefined && failedAs === encoded.signature())
+                            continue;
+                        if (this.#forced.has(key) || encoded.changed)
+                            pending.push(encoded);
+                    }
+                    for (const encoded of pending) {
                         if (!this.live())
                             return;
-                        const encoded = JSON.stringify(value);
+                        const key = encoded.key;
                         this.#forced.delete(key);
                         try {
-                            await this.write(key, wireValue(value));
-                            this.#sent.set(key, encoded);
+                            this.#sent.set(key, await this.#send(encoded));
                             this.#failed.delete(key);
                             this.#backoff = 0;
                             this.#broken = false;
@@ -222,7 +436,7 @@ export class ViewBase {
                             if (!this.#broken)
                                 failure ??= error;
                             this.#broken = true;
-                            this.#failed.set(key, encoded);
+                            this.#failed.set(key, encoded.signature());
                         }
                     }
                 } while (pending.length && !failed && this.live());
@@ -294,8 +508,8 @@ class WindowHandle extends ViewBase {
     live() {
         return this.#opened && !this.closed;
     }
-    write(property, value) {
-        return this.scope.runtime.host.ui.set(this.#id, property, value);
+    write(property, write) {
+        return this.scope.runtime.host.ui.set(this.#id, property, write);
     }
     on(callback, handler) {
         // The host forwards only callbacks named when the window opens.
@@ -400,8 +614,8 @@ class PanelHandle extends ViewBase {
     live() {
         return this.#mounted && !this.closed;
     }
-    write(property, value) {
-        return this.scope.runtime.host.ui.setMount(property, value);
+    write(property, write) {
+        return this.scope.runtime.host.ui.setMount(property, write);
     }
     get state() {
         const service = layoutOf(this.scope.runtime);

package/dist/wire.d.ts

@@ -56,6 +56,45 @@ export interface UiCallback {
     callback: string;
     args: Json[];
 }
+/**
+ * One row operation of a patch, by index, applied to the result of the
+ * ones before (player 0.6.0, feature `ui.patch`). `move` takes `count` rows
+ * out at `from` and puts them back at `to`, an index of the list without
+ * them.
+ */
+export type RowOp = {
+    op: "set";
+    at: number;
+    row: Json;
+} | {
+    op: "insert";
+    at: number;
+    rows: Json[];
+} | {
+    op: "remove";
+    at: number;
+    count: number;
+} | {
+    op: "move";
+    from: number;
+    count: number;
+    to: number;
+};
+/**
+ * A property write: a whole value (with its `seq` to players that take
+ * patches), or a row patch of an array applying on the write numbered
+ * `base` (0: the initial properties).
+ */
+export type PropertyWrite = {
+    value: Json;
+    seq?: number;
+} | {
+    patch: {
+        base: number;
+        seq: number;
+        ops: RowOp[];
+    };
+};
 /**
  * A definite refusal from the player (or the plugin runner), with a stable
  * `code`. Plugin code sees it as a `PluginError` (an `Error` with `code`);
@@ -481,7 +520,7 @@ export declare function createWire(transport: Transport): {
             global: string;
             properties: Record<string, Json>;
         }) => Promise<void>;
-        set: (id: string, property: string, value: Json) => Promise<void>;
+        set: (id: string, property: string, write: PropertyWrite) => Promise<void>;
         unregister: (id: string) => Promise<void>;
         show: (id?: string) => Promise<void>;
     };
@@ -668,7 +707,7 @@ export declare function createWire(transport: Transport): {
             prepareMs: number;
             shellGeneration: number;
         }>;
-        setMount: (property: string, value: Json) => Promise<void>;
+        setMount: (property: string, write: PropertyWrite) => Promise<void>;
         interaction: (locks: {
             focused: boolean;
             dragging: boolean;
@@ -677,7 +716,7 @@ export declare function createWire(transport: Transport): {
         unmount: () => Promise<void>;
         menu: (items: (string | null)[], x: number, y: number) => Promise<void>;
         open: (id: string, file: string, properties?: Record<string, Json>, callbacks?: string[]) => Promise<void>;
-        set: (id: string, property: string, value: Json) => Promise<void>;
+        set: (id: string, property: string, write: PropertyWrite) => Promise<void>;
         show: (id: string, visible: boolean) => Promise<void>;
         close: (id: string) => Promise<void>;
     };

package/dist/wire.js

@@ -125,7 +125,7 @@ export function createWire(transport) {
         /** Settings pages in the player's options window (`ui.settings`). */
         settings: {
             register: (options) => transport.request("settings.register", options),
-            set: (id, property, value) => transport.request("settings.set", { id, property, value }),
+            set: (id, property, write) => transport.request("settings.set", { id, property, ...write }),
             unregister: (id) => transport.request("settings.unregister", { id }),
             show: (id) => transport.request("settings.show", id === undefined ? {} : { id }),
         },
@@ -321,12 +321,12 @@ export function createWire(transport) {
                 base,
             }),
             mount: (options) => transport.request("ui.mount", options),
-            setMount: (property, value) => transport.request("ui.setMount", { property, value }),
+            setMount: (property, write) => transport.request("ui.setMount", { property, ...write }),
             interaction: (locks) => transport.request("ui.interaction", locks),
             unmount: () => transport.request("ui.unmount"),
             menu: (items, x, y) => transport.request("ui.menu", { items, x, y }),
             open: (id, file, properties = {}, callbacks = []) => transport.request("ui.open", { id, file, properties, callbacks }),
-            set: (id, property, value) => transport.request("ui.set", { id, property, value }),
+            set: (id, property, write) => transport.request("ui.set", { id, property, ...write }),
             show: (id, visible) => transport.request("ui.show", { id, visible }),
             close: (id) => transport.request("ui.close", { id }),
         },