@vestra-player/sdk 1.5.43 → 1.5.44

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.5.44
+
+**Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. How the SDK sends array properties changes, on players that take it (player 0.6.0); with older players it sends whole values as before. The read-only copy of the widget library gains components that need player 0.6.0 (`"minPlayerVersion": "0.6.0"` for a plugin whose Slint uses them; an older player fails to compile such a file).
+
+- **Row patches.** When a bound or set array changes, the SDK sends the rows that changed instead of the whole array: `set`, `insert`, `remove` and `move` operations by index (wire: `ui.setMount`, `ui.set` and `settings.set` with `patch: { base, seq, ops }` instead of `value`; whole writes carry `seq`). Rows are matched by a `key`, `id`, `rowId` or `row-id` field when every row has one, unique, as a string or number (moves are kept to a minimum); otherwise by index, with the unchanged rows at both ends left out. The player writes the rows into its live model in place, without comparing the whole array: selecting one row of a 200-row list costs one row. A player that cannot apply a patch answers `stale` and the SDK sends the whole value at once. Whole values are sent as before when the player does not advertise the feature (`features: ["ui.patch"]` in its start-up data), after a failed write, for rows written into an empty array, for rows holding a Markdown document, and for a value over the limits (refused with `limit`, as before).
+  After two `stale` answers in a row for a property, it is sent whole until the view shows its initial properties again. The limit counts see what is sent: an image or document handle is one value, any other object with `toJSON` (a `Date`) counts as what it returns, and a hole in a sparse array is `null`. A released image is refused in any row of the array, also in rows a patch keeps, as in a whole write. Your Slint code must not write into the rows of an array property: a patch does not overwrite rows whose value did not change ([Arrays: only the changed rows are sent](docs/explanation/ui.md#arrays-only-the-changed-rows-are-sent)). `set()` with an unchanged array sends it whole.
+- **Cheaper update passes.** A scalar property is compared with what was sent without `JSON.stringify`; an array is encoded row by row, the same work as before.
+- **`TestHost`** takes patches as the player does (`base`, `stale`, the checks on operations and the value limits on the result) and keeps whole values in `props`, so tests see no difference. It advertises the feature; `host.app = { ...host.app, features: [] }` before `startPlugin` gives an older player's behaviour.
+- **`@vestra/widgets.slint`** (the read-only copy of the player's widget library, player 0.6.0): the widget library copy gains `Check`, `Radio`, `RadioMark`, `RadioGroup`, `Tab`, `Tabs` and `Choice` (a drop-down), drawn in the player's theme with a keyboard focus ring; `Slider` takes the keyboard (arrow keys by `step`, a twentieth of the range by default) and reports `has-focus`. A Slint file that imports them needs player 0.6.0. `Check` takes `self-toggle: false` for a state the plugin decides (a confirmation first); `Tabs` takes `emphasis` per tab; `Slider` takes `focusable: false` to stay out of the Tab order; `Choice` takes `window-height` so its list fits a short window. `@vestra/markdown.slint`: `MarkdownView` builds only the blocks on screen (a `ListView`), so long documents cost what is visible.
+
 ## 1.5.43
 
 **Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`, no new capability. The new API needs player 0.5.25 (`"minPlayerVersion": "0.5.25"`); older players leave the new fields out and refuse the new event (the listener never fires). The `decoding` reason code stays as it is: the cause is a new optional field beside it.
@@ -10,7 +20,6 @@
 - **`TestHost`**: `upscalingDecoding(cause, plugins?)` fakes each cause with the player's message (and a matching `upscaling.hwdecCurrent`); `upscaling.video`, `area`, `gpu`, `hwdecCurrent` (defaults: 1080p on a 4K area, an RTX 4070, `d3d11va`; `inChain` follows `requested`); `upscalingChanged()` sends the event to a listening plugin.
 - The player's capability table copy (`video.upscaling.changed` under `video.upscaling`) and `CAPABILITY_INFO` (`VideoUpscaling.onChange`) follow.
 
-
 ## 1.5.42
 
 **Who must change: nobody.** Documentation only: no API changes, `apiVersion` stays `vestra/1`, no player version needed. The package's code is the same as 1.5.41; the doc comments' `@see` links (27 in `src/plugin/types.ts`) now point at `docs/explanation/` instead of `docs/concepts/`. The site's page addresses stay the same, and the old _Concepts_ group address redirects to _Explanation_; `llms.txt` and `llms-full.txt` follow the new pages.

package/dist/player-runtime.d.ts

@@ -24,3 +24,4 @@ export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.ts";
 export { MARKDOWN_LIMITS } from "./plugin/markdown.ts";
 export { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./plugin/values.ts";
+export { PATCH_FEATURE, PATCH_OPS } from "./plugin/patch.ts";

package/dist/player-runtime.js

@@ -22,3 +22,4 @@ export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.js";
 export { MARKDOWN_LIMITS } from "./plugin/markdown.js";
 export { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./plugin/values.js";
+export { PATCH_FEATURE, PATCH_OPS } from "./plugin/patch.js";

package/dist/plugin/patch.d.ts

@@ -0,0 +1,101 @@
+/** The player feature that takes row patches. */
+export declare const PATCH_FEATURE = "ui.patch";
+/** The most operations one patch carries (the player's `MAX_PATCH_OPS`). */
+export declare const PATCH_OPS = 1024;
+/**
+ * Fields that identify a row, in the order they are tried. A field is used
+ * when every row has it, as a string or a number, and no two rows share it.
+ */
+export declare const KEY_FIELDS: readonly string[];
+export type RowKey = string | number;
+/** One planned operation; `set` and `insert` name rows of the new array. */
+export type PlannedOp = {
+    op: "set";
+    at: number;
+    row: number;
+} | {
+    op: "insert";
+    at: number;
+    rows: number[];
+} | {
+    op: "remove";
+    at: number;
+    count: number;
+} | {
+    op: "move";
+    from: number;
+    count: number;
+    to: number;
+};
+/** What one row counts toward the value limits (as a row of an array). */
+export interface RowCount {
+    values: number;
+    text: number;
+    /** Over a per-row limit (a string, the depth): the whole value is sent. */
+    over: boolean;
+}
+/** An array as sent: each row's JSON, its key field and keys, its counts. */
+export interface Rows {
+    enc: string[];
+    field: string | null;
+    keys: RowKey[] | null;
+    /** Filled in as patches need them. */
+    counts: (RowCount | undefined)[];
+}
+/**
+ * The field that identifies `rows`, and each row's key; `null` when no
+ * field of {@link KEY_FIELDS} does (rows are then matched by index).
+ */
+export declare function keyOf(rows: readonly unknown[]): {
+    field: string;
+    keys: RowKey[];
+} | null;
+/**
+ * What `row` counts toward the value limits as a row of an array (depth
+ * 1), like `valueLimitProblem` on the row as sent: every value one, an
+ * image one, a document one and its text, strings and field names their
+ * UTF-8 bytes. Any other object with `toJSON` counts as what it returns.
+ */
+export declare function countRow(row: unknown): RowCount;
+/** The new array is within the value limits (counted per row). */
+export declare function withinLimits(counts: readonly RowCount[]): boolean;
+/**
+ * The operations that turn the old rows into the new ones (`null`: more
+ * than {@link PATCH_OPS} would be needed), and for each new row the old row
+ * whose JSON it keeps (`-1`: a new or changed row). Keyed when both arrays
+ * have keys from the same field; otherwise by index.
+ */
+export declare function diff(old: {
+    enc: readonly string[];
+    keys: readonly RowKey[] | null;
+}, next: {
+    enc: readonly string[];
+    keys: readonly RowKey[] | null;
+}): {
+    ops: PlannedOp[];
+    from: Int32Array;
+} | null;
+/**
+ * Apply planned operations to a copy of `old` (the rows' JSON), taking new
+ * rows from `next`: the check that a diff produces exactly the new rows.
+ */
+export declare function replay(old: readonly string[], ops: readonly PlannedOp[], next: readonly string[]): string[];
+/** Apply wire operations to an array (the TestHost's copy of a value). */
+export declare function applyOps<T>(rows: T[], ops: readonly ({
+    op: "set";
+    at: number;
+    row: T;
+} | {
+    op: "insert";
+    at: number;
+    rows: T[];
+} | {
+    op: "remove";
+    at: number;
+    count: number;
+} | {
+    op: "move";
+    from: number;
+    count: number;
+    to: number;
+})[]): T[];

package/dist/plugin/patch.js

@@ -0,0 +1,337 @@
+/**
+ * Row patches of array properties (player 0.6.0, feature `ui.patch`): the
+ * diff between the rows last sent and the rows bound now, as `set`,
+ * `insert`, `remove` and `move` operations by index. Internal; plugins see
+ * none of it (the player's doc/architecture/large-lists.md §2).
+ */
+import { UI_VALUE_LIMITS } from "./values.js";
+/** The player feature that takes row patches. */
+export const PATCH_FEATURE = "ui.patch";
+/** The most operations one patch carries (the player's `MAX_PATCH_OPS`). */
+export const PATCH_OPS = 1024;
+/**
+ * Fields that identify a row, in the order they are tried. A field is used
+ * when every row has it, as a string or a number, and no two rows share it.
+ */
+export const KEY_FIELDS = ["key", "id", "rowId", "row-id"];
+const plain = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+/**
+ * The field that identifies `rows`, and each row's key; `null` when no
+ * field of {@link KEY_FIELDS} does (rows are then matched by index).
+ */
+export function keyOf(rows) {
+    const first = rows[0];
+    if (!plain(first))
+        return null;
+    for (const field of KEY_FIELDS) {
+        if (!(field in first))
+            continue;
+        const keys = [];
+        const seen = new Set();
+        let ok = true;
+        for (let i = 0; i < rows.length; i++) {
+            const row = rows[i];
+            const key = plain(row) ? row[field] : undefined;
+            if ((typeof key !== "string" && typeof key !== "number") ||
+                seen.has(key)) {
+                ok = false;
+                break;
+            }
+            seen.add(key);
+            keys.push(key);
+        }
+        if (ok)
+            return { field, keys };
+    }
+    return null;
+}
+const bytes = (text) => Buffer.byteLength(text, "utf8");
+/**
+ * `value` as `JSON.stringify` writes it: an object's `toJSON` result
+ * (once), `undefined` for what it leaves out (a function, a symbol).
+ */
+function jsonOf(value) {
+    if (value !== null &&
+        typeof value === "object" &&
+        !("__vestraImage" in value) &&
+        !("__vestraMarkdown" in value) &&
+        typeof value.toJSON === "function")
+        return value.toJSON();
+    return typeof value === "function" || typeof value === "symbol"
+        ? undefined
+        : value;
+}
+/**
+ * What `row` counts toward the value limits as a row of an array (depth
+ * 1), like `valueLimitProblem` on the row as sent: every value one, an
+ * image one, a document one and its text, strings and field names their
+ * UTF-8 bytes. Any other object with `toJSON` counts as what it returns.
+ */
+export function countRow(row) {
+    const count = { values: 0, text: 0, over: false };
+    const L = UI_VALUE_LIMITS;
+    const text = (s) => {
+        const n = bytes(s);
+        if (n > L.stringBytes)
+            count.over = true;
+        count.text += n;
+    };
+    const walk = (value, depth) => {
+        if (count.over)
+            return;
+        if (depth > L.depth) {
+            count.over = true;
+            return;
+        }
+        count.values += 1;
+        if (value !== null && typeof value === "object") {
+            if ("__vestraImage" in value)
+                return;
+            if ("__vestraMarkdown" in value) {
+                count.text += bytes(value.text);
+                return;
+            }
+        }
+        if (typeof value === "string")
+            return text(value);
+        if (Array.isArray(value)) {
+            if (value.length > L.arrayRows)
+                count.over = true;
+            // Array.from: a hole is `null`, as `JSON.stringify` writes it.
+            for (const item of Array.from(value))
+                walk(jsonOf(item) ?? null, depth + 1);
+            return;
+        }
+        if (value !== null && typeof value === "object")
+            for (const [name, raw] of Object.entries(value)) {
+                const item = jsonOf(raw);
+                if (item === undefined)
+                    continue;
+                text(name);
+                walk(item, depth + 1);
+            }
+    };
+    walk(jsonOf(row) ?? null, 1);
+    return count;
+}
+/** The new array is within the value limits (counted per row). */
+export function withinLimits(counts) {
+    const L = UI_VALUE_LIMITS;
+    if (counts.length > L.arrayRows)
+        return false;
+    let values = 1;
+    let text = 0;
+    for (const count of counts) {
+        if (count.over)
+            return false;
+        values += count.values;
+        text += count.text;
+    }
+    return values <= L.values && text <= L.textBytes;
+}
+/** The longest increasing subsequence of `values`, as a set of indices. */
+function increasing(values) {
+    const tails = [];
+    const before = new Int32Array(values.length).fill(-1);
+    for (let i = 0; i < values.length; i++) {
+        let lo = 0;
+        let hi = tails.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (values[tails[mid]] < values[i])
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        if (lo > 0)
+            before[i] = tails[lo - 1];
+        tails[lo] = i;
+    }
+    const out = new Set();
+    for (let i = tails.at(-1) ?? -1; i >= 0; i = before[i])
+        out.add(i);
+    return out;
+}
+/**
+ * The operations that turn the old rows into the new ones (`null`: more
+ * than {@link PATCH_OPS} would be needed), and for each new row the old row
+ * whose JSON it keeps (`-1`: a new or changed row). Keyed when both arrays
+ * have keys from the same field; otherwise by index.
+ */
+export function diff(old, next) {
+    const from = new Int32Array(next.enc.length).fill(-1);
+    const ops = old.keys && next.keys
+        ? keyed(old.enc, old.keys, next.enc, next.keys, from)
+        : byIndex(old.enc, next.enc, from);
+    return ops && ops.length <= PATCH_OPS ? { ops, from } : null;
+}
+function byIndex(old, next, from) {
+    const min = Math.min(old.length, next.length);
+    let p = 0;
+    while (p < min && old[p] === next[p])
+        from[p] = p++;
+    let s = 0;
+    while (s < min - p && old[old.length - 1 - s] === next[next.length - 1 - s]) {
+        from[next.length - 1 - s] = old.length - 1 - s;
+        s++;
+    }
+    const ops = [];
+    const middle = Math.min(old.length, next.length) - p - s;
+    for (let i = p; i < p + middle; i++)
+        if (old[i] === next[i])
+            from[i] = i;
+        else
+            ops.push({ op: "set", at: i, row: i });
+    const at = p + middle;
+    if (next.length > old.length)
+        ops.push({
+            op: "insert",
+            at,
+            rows: Array.from({ length: next.length - old.length }, (_, k) => at + k),
+        });
+    else if (old.length > next.length)
+        ops.push({ op: "remove", at, count: old.length - next.length });
+    return ops;
+}
+function keyed(oldEnc, oldKeys, newEnc, newKeys, from) {
+    const sets = [];
+    const keep = (j, i) => {
+        if (oldEnc[i] === newEnc[j])
+            from[j] = i;
+        else
+            sets.push({ op: "set", at: j, row: j });
+    };
+    const min = Math.min(oldKeys.length, newKeys.length);
+    let p = 0;
+    while (p < min && oldKeys[p] === newKeys[p])
+        keep(p, p++);
+    let s = 0;
+    while (s < min - p &&
+        oldKeys[oldKeys.length - 1 - s] === newKeys[newKeys.length - 1 - s]) {
+        keep(newKeys.length - 1 - s, oldKeys.length - 1 - s);
+        s++;
+    }
+    const oldEnd = oldKeys.length - s;
+    const newEnd = newKeys.length - s;
+    // The new middle's keys, by position (relative to p).
+    const target = new Map();
+    for (let j = p; j < newEnd; j++)
+        target.set(newKeys[j], j - p);
+    const ops = [];
+    // Removes, from the end so that indices stay valid; runs merged.
+    const kept = [];
+    const oldAt = new Map();
+    for (let i = oldEnd - 1; i >= p; i--) {
+        if (target.has(oldKeys[i]))
+            continue;
+        const last = ops.at(-1);
+        if (last?.op === "remove" && last.at === i + 1) {
+            last.at = i;
+            last.count++;
+        }
+        else
+            ops.push({ op: "remove", at: i, count: 1 });
+        if (ops.length > PATCH_OPS)
+            return null;
+    }
+    for (let i = p; i < oldEnd; i++)
+        if (target.has(oldKeys[i])) {
+            oldAt.set(oldKeys[i], i);
+            kept.push(oldKeys[i]);
+        }
+    // Moves: every kept row outside a longest increasing run of target
+    // positions goes right after the kept row before it in the new order.
+    const positions = kept.map((key) => target.get(key));
+    const stay = increasing(positions);
+    if (kept.length - stay.size + ops.length > PATCH_OPS)
+        return null;
+    const stays = new Set();
+    for (const index of stay)
+        stays.add(kept[index]);
+    const current = kept.slice();
+    let previous;
+    for (let j = p; j < newEnd; j++) {
+        const key = newKeys[j];
+        if (!oldAt.has(key))
+            continue;
+        if (!stays.has(key)) {
+            const at = current.indexOf(key);
+            current.splice(at, 1);
+            const to = previous === undefined ? 0 : current.indexOf(previous) + 1;
+            current.splice(to, 0, key);
+            if (at !== to)
+                ops.push({ op: "move", from: p + at, count: 1, to: p + to });
+        }
+        previous = key;
+    }
+    // Inserts, from the top; runs merged.
+    for (let j = p; j < newEnd; j++) {
+        const key = newKeys[j];
+        if (oldAt.has(key)) {
+            keep(j, oldAt.get(key));
+            continue;
+        }
+        const last = ops.at(-1);
+        if (last?.op === "insert" && last.at + last.rows.length === j)
+            last.rows.push(j);
+        else
+            ops.push({ op: "insert", at: j, rows: [j] });
+        if (ops.length > PATCH_OPS)
+            return null;
+    }
+    sets.sort((a, b) => a.at - b.at);
+    for (const set of sets) {
+        ops.push(set);
+        if (ops.length > PATCH_OPS)
+            return null;
+    }
+    return ops;
+}
+/**
+ * Apply planned operations to a copy of `old` (the rows' JSON), taking new
+ * rows from `next`: the check that a diff produces exactly the new rows.
+ */
+export function replay(old, ops, next) {
+    const rows = old.slice();
+    for (const op of ops)
+        switch (op.op) {
+            case "set":
+                rows[op.at] = next[op.row];
+                break;
+            case "insert":
+                rows.splice(op.at, 0, ...op.rows.map((j) => next[j]));
+                break;
+            case "remove":
+                rows.splice(op.at, op.count);
+                break;
+            case "move":
+                rows.splice(op.to, 0, ...rows.splice(op.from, op.count));
+                break;
+        }
+    return rows;
+}
+/** Apply wire operations to an array (the TestHost's copy of a value). */
+export function applyOps(rows, ops) {
+    const out = rows.slice();
+    for (const op of ops)
+        switch (op.op) {
+            case "set":
+                out[op.at] = op.row;
+                break;
+            case "insert":
+                out.splice(op.at, 0, ...op.rows);
+                break;
+            case "remove":
+                out.splice(op.at, op.count);
+                break;
+            case "move":
+                out.splice(op.to, 0, ...out.splice(op.from, op.count));
+                break;
+        }
+    return out;
+}

package/dist/plugin/runtime.d.ts

@@ -54,6 +54,12 @@ export declare class Runtime {
     readonly app: App;
     /** `plugin.i18n.locale`, from the start-up handshake; English when unknown. */
     readonly locale: Locale;
+    /**
+     * Protocol additions the player advertises at start-up (`features` in the
+     * handshake's app data, player 0.6.0): `ui.patch` (row patches of
+     * property writes). Not part of the plugin API; empty for older players.
+     */
+    readonly features: ReadonlySet<string>;
     constructor(transport: Transport, manifest: PluginManifest, directory: string, dataDirectory?: string, app?: unknown);
     can(capability: string): boolean;
     /** Lazily created singletons shared by every scope of this plugin. */

package/dist/plugin/runtime.js

@@ -132,6 +132,12 @@ export class Runtime {
     app;
     /** `plugin.i18n.locale`, from the start-up handshake; English when unknown. */
     locale;
+    /**
+     * Protocol additions the player advertises at start-up (`features` in the
+     * handshake's app data, player 0.6.0): `ui.patch` (row patches of
+     * property writes). Not part of the plugin API; empty for older players.
+     */
+    features;
     constructor(transport, manifest, directory, dataDirectory, app) {
         this.#transport = transport;
         this.dataDirectory = dataDirectory;
@@ -139,6 +145,11 @@ export class Runtime {
         this.host = createWire(transport);
         const host = this.host;
         this.app = appInfo(app, () => host.app.system());
+        const features = app
+            ?.features;
+        this.features = new Set(Array.isArray(features)
+            ? features.filter((name) => typeof name === "string")
+            : []);
         this.locale = LOCALES.includes(transport.locale ?? "")
             ? transport.locale
             : "en";

package/dist/plugin/settings.js

@@ -61,8 +61,8 @@ class Page extends ViewBase {
     live() {
         return this.#registered && !this.closed;
     }
-    write(property, value) {
-        return this.scope.runtime.host.settings.set(this.#id, property, value);
+    write(property, write) {
+        return this.scope.runtime.host.settings.set(this.#id, property, write);
     }
     async dispose() {
         if (this.closed)