@vestra-player/sdk 1.5.45 → 1.5.47

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.5.47
+
+**Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. The built-in command table follows player 0.6.0's new default keys: a plugin whose documentation or tests list the player's default keys (from `BUILTIN_COMMANDS`, or Escape, Enter, F11 and the side mouse buttons by hand) should update them.
+
+- **Player 0.6.0 default keys** (`BUILTIN_COMMANDS`, the generated key tables, `HostAction`): **Toggle Fullscreen** (`host/fullscreen`) is `Escape` only (up to 0.5.x `Enter`, `Alt+Enter`, `F11`); **Leave Fullscreen** (`host/exit-fullscreen`) has no default key (up to 0.5.x `Escape`); the new **Enter Fullscreen** (`host/enter-fullscreen`) has no default key and no menu row and is enabled only when windowed (Leave Fullscreen only in fullscreen); **Previous** is `PageUp`, `Mouse:X2` and **Next** `PageDown`, `Mouse:X1` (the side buttons swapped: back is next, forward is previous). The side buttons now fire anywhere in the main window or the floating sidebar window, except while a menu is open, not only over the video. `host.run` takes the same actions as before (`fullscreen` toggles). `TestHost`'s core actions use the new Previous / Next bindings.
+- **Rows that cannot change are not encoded again.** An update pass encodes every row of a bound array to find the changed ones; in a 20,000-row list that was about 40% of a click. A deep-frozen row (`Object.freeze` on it and on everything inside it: plain objects and arrays, no getters, no own `toJSON`; image and document handles allowed: they are immutable, their wire form is fixed when made, so they need no freezing) that the bind function returns again is now encoded once more and then taken from a cache kept by the row object (weakly: a row the plugin drops goes with its entry), with its limit counts. Rows that are not frozen, or hold a mutable part, are encoded on every pass as before, so changes made in place are still sent. To benefit, keep an unchanged row as the same frozen object and make a new one when it changes ([Arrays: only the changed rows are sent](docs/explanation/ui.md#arrays-only-the-changed-rows-are-sent)). Measured in the test host with the playlist at 20,000 rows memoized that way: a click from about 24 ms to about 14 ms to the rows write.
+- _Commands, menus and key bindings_: the example of a disabled command letting its key go no longer uses Escape on Leave Fullscreen.
+
+## 1.5.46
+
+**Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. The new limits and the split writes take effect with player 0.6.0 (large lists P3); with older players arrays are sent whole as before and the old limits apply there. **A plugin that binds a whole long list depends on them: set `"minPlayerVersion": "0.6.0"`.**
+
+- **Whole lists.** `UI_VALUE_LIMITS` follow player 0.6.0: 100,000 rows per array (was 4,096), 1,048,576 values (was 16,384) and 32 MiB of text (was 1 MiB) in one property value. A plugin binds its whole list; a long list should be drawn with a Slint `ListView` (a `for` builds every row). The windowing example is replaced by a whole-list one.
+- **Writes larger than one request are split.** The protocol line stays 1 MiB (`MESSAGE_LIMIT`). With a player that takes row patches:
+  - an array whose rows exceed 512 KiB (`CHUNK_BYTES`, internal) is sent as a whole write of its first rows and `insert` patches of the rest, each applying on the one before; every part but the last carries `more: true`, and the player holds them and writes the whole value at the last, so a list it already shows changes once (its scroll position and selection stay);
+  - a patch carrying more is sent as several patches, each applying on the one before; a diff may now plan up to 16,384 operations (at most 1,024 moves), sent 1,024 at most per patch, before the value goes whole;
+  - the initial properties of `panels.mount`, `ui.open` and `settings.page` carry at most 512 KiB of rows together: the first rows show at once and the rest follows as patches on the first update;
+  - only a property's top-level array is split, and not one whose rows hold Markdown documents (sent whole as before: the player merges documents in place); any other value, and each row, must fit in one request. A row of more than 512 KiB, or a value over the limits, is refused with `limit` before any part is sent;
+  - when the view closes or shows its initial properties again while a write goes in parts, the rest is dropped without an error and the view's next update sends what it shows; any other failure part-way leaves no base, so the next write of the property is whole (in parts again).
+- **`vestra-plugin check` warns** (a reminder, never a failure) where a plugin's .slint file puts a `for` over an array it binds (an `in` or `in-out` array property) outside a `ListView`: such a `for` builds every row up front.
+- **`null` for an image in a row** shows no picture (player 0.6.0), so rows without a thumbnail need no placeholder image.
+- **`TestHost`** enforces the new limits and takes the split writes like the player (each line within `MESSAGE_LIMIT`, parts with `more` held until the last); `props` hold whole values as before.
+
 ## 1.5.45
 
 **Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. Only when the SDK re-evaluates bindings changes; what a plugin's views and commands show stays the same. One case can show in tests: a plugin that changes state outside a handler (a timer, a promise continuation after the handler returned, a child process) without calling `plugin.update()`, and a test that relied on `host.setSource(...)` to refresh it. Have the plugin call `plugin.update()` after such a change (as the documentation always said), or wait `await host.settle(1000)` in the test; `settle()` does not wait for the once-a-second full pass.

package/bin/vestra-plugin.mjs

@@ -357,7 +357,10 @@ async function check(target, report = null) {
   }
   say(`${target.name}: capabilities declared for every API use`);
   if (report) return;
-  for (const line of await bottomBarWarnings(target))
+  for (const line of [
+    ...(await bottomBarWarnings(target)),
+    ...(await forWarnings(target)),
+  ])
     console.log(`${target.name}: warning: ${line}`);
   // Translation warnings never fail the check.
   if (present(join(target.directory, "locales"))) {
@@ -502,6 +505,61 @@ async function bottomBarWarnings(target) {
   return warnings;
 }
 
+/**
+ * A `for` over an array the plugin binds (an `in` or `in-out` property of
+ * array type of a component or global in the same file), outside a
+ * `ListView`, in the plugin's .slint files: a reminder, not a failure
+ * (SDK 1.5.46). Such a `for` builds every row of the array up front; since
+ * player 0.6.0 a plugin may bind a whole long list, which belongs in a
+ * `ListView` (it builds only the rows on screen). A text scan: imported
+ * components and `@children` are not followed.
+ */
+async function forWarnings(target) {
+  const { slint } = await sourceFiles(target);
+  const warnings = [];
+  for (const file of slint) {
+    const text = slintCode(
+      await readFile(join(target.directory, file), "utf8"),
+    );
+    const arrays = new Set(
+      [
+        ...text.matchAll(
+          /\b(?:in|in-out)\s+property\s*<\s*\[[^\]]*\]\s*>\s*([A-Za-z_][\w-]*)/g,
+        ),
+      ].map((match) => match[1]),
+    );
+    if (!arrays.size) continue;
+    // The elements open at each point: the name before each `{`.
+    const open = [];
+    let line = 1;
+    for (let i = 0; i < text.length; i++) {
+      const c = text[i];
+      if (c === "\n") line++;
+      else if (c === "{") {
+        const name = /([A-Za-z_][\w-]*)\s*$/.exec(
+          text.slice(Math.max(0, i - 80), i),
+        );
+        open.push(name ? name[1] : "");
+      } else if (c === "}") open.pop();
+      else if (
+        text.startsWith("for", i) &&
+        !/[\w-]/.test(text[i - 1] ?? " ") &&
+        /\s/.test(text[i + 3] ?? "")
+      ) {
+        const loop =
+          /^for\s+[\w-]+(?:\s*\[\s*[\w-]+\s*\])?\s+in\s+([\w.-]+)/.exec(
+            text.slice(i, i + 200),
+          );
+        const array = loop?.[1].split(".").at(-1);
+        if (array && arrays.has(array) && !open.includes("ListView"))
+          warnings.push(
+            `${file.replaceAll("\\", "/")}:${line}: \`for\` over the bound array \`${array}\` outside a ListView builds every row; a long list should use a ListView (docs/reference/limits.md)`,
+          );
+      }
+    }
+  }
+  return warnings;
+}
 /** The plugin's own production .ts / .mts and .slint files. */
 async function sourceFiles(target) {
   const all = await files(target.directory);

package/dist/commands.js

@@ -265,8 +265,8 @@ vestra.playback | copy-name | Copy to Clipboard ▸ File Name
 vestra.playback | copy-folder | Copy to Clipboard ▸ Folder Path
 vestra.playback | copy-path | Copy to Clipboard ▸ Full Path
 host | play-pause | Playback ▸ Play/Pause | Space, Mouse:LeftClick
-host | previous | Playback ▸ Previous | PageUp, Mouse:X1
-host | next | Playback ▸ Next | PageDown, Mouse:X2
+host | previous | Playback ▸ Previous | PageUp, Mouse:X2
+host | next | Playback ▸ Next | PageDown, Mouse:X1
 host | frame-back | Playback ▸ Seek ▸ Previous Frame | D
 host | frame-forward | Playback ▸ Seek ▸ Next Frame | F
 vestra.playback | keyframe-back | Playback ▸ Seek ▸ Previous Keyframe | Ctrl+Shift+ArrowLeft
@@ -492,7 +492,7 @@ vestra.audio | audio.normalize | Audio ▸ Processing ▸ Normalize | Shift+N
 vestra.audio | audio.clarity | Audio ▸ Processing ▸ Crystalizer | Shift+C
 vestra.audio | audio.reset | Audio ▸ Reset
 vestra.visualizer | audio-cover | Audio ▸ Show Album Cover for Audio Only
-host | fullscreen | Toggle Fullscreen | Enter, Alt+Enter, F11
+host | fullscreen | Toggle Fullscreen | Escape
 vestra.window | pip | Screen ▸ Picture-in-Picture
 vestra.window | mini | Screen ▸ Mini Size | \`
 vestra.window | size.0.5 | Screen ▸ 0.5× | 1
@@ -536,7 +536,8 @@ vestra.preferences | language.fr | Settings ▸ Language ▸ Français
 vestra.preferences | language.es | Settings ▸ Language ▸ Español
 vestra.info | info.about | About Vestra Player… | F1
 host | quit | Quit | Cmd+Q
-host | exit-fullscreen | (Leave Fullscreen) | Escape
+host | enter-fullscreen | (Enter Fullscreen)
+host | exit-fullscreen | (Leave Fullscreen)
 host | sidebar | (Toggle Sidebar)
 vestra.info | info.brief | (Brief Info) | Shift+Tab
 vestra.playlist | playlist.play | (Play) | Enter, P | panel

package/dist/plugin/bindings.d.ts

@@ -66,8 +66,11 @@ export declare const BINDING_INPUTS: Readonly<{
      */
     readonly named: readonly ["Space", "Enter", "Tab", "Escape", "Backspace", "Delete", "Insert", "Home", "End", "PageUp", "PageDown", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Plus", ...string[], "NumpadPlus", "NumpadMinus", "NumpadMultiply", "NumpadDivide", "NumpadEnter", "NumpadDecimal"];
     /**
-     * Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the
-     * halves of the video apart for a double click.
+     * Mouse inputs on the video area; the side buttons `Mouse:X1` (back) and
+     * `Mouse:X2` (forward) anywhere in the main window or the floating sidebar
+     * window, except while a menu is open (player 0.6.0).
+     * `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a
+     * double click.
      */
     readonly mouse: readonly ["Mouse:LeftClick", "Mouse:LeftDoubleClick", "Mouse:LeftDoubleClick:LeftHalf", "Mouse:LeftDoubleClick:RightHalf", "Mouse:MiddleClick", "Mouse:X1", "Mouse:X2", "Mouse:WheelUp", "Mouse:WheelDown", "Mouse:WheelLeft", "Mouse:WheelRight"];
 }>;

package/dist/plugin/bindings.js

@@ -97,8 +97,11 @@ export const BINDING_INPUTS = Object.freeze({
         "NumpadDecimal",
     ],
     /**
-     * Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the
-     * halves of the video apart for a double click.
+     * Mouse inputs on the video area; the side buttons `Mouse:X1` (back) and
+     * `Mouse:X2` (forward) anywhere in the main window or the floating sidebar
+     * window, except while a menu is open (player 0.6.0).
+     * `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a
+     * double click.
      */
     mouse: [
         "Mouse:LeftClick",

package/dist/plugin/patch.d.ts

@@ -2,6 +2,12 @@
 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;
+/**
+ * The most operations one diff plans (SDK 1.5.46): its patch is sent as
+ * several of at most {@link PATCH_OPS} each (`chunkOps`); more is sent whole
+ * (in parts, which the player writes at once).
+ */
+export declare const DIFF_OPS: number;
 /**
  * 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.
@@ -61,7 +67,8 @@ export declare function countRow(row: unknown): RowCount;
 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
+ * than {@link DIFF_OPS} would be needed, or more than {@link PATCH_OPS}
+ * moves), 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.
  */
@@ -99,3 +106,47 @@ export declare function applyOps<T>(rows: T[], ops: readonly ({
     count: number;
     to: number;
 })[]): T[];
+/**
+ * The bytes of rows one write carries at most (SDK 1.5.46, player 0.6.0):
+ * half the 1 MiB protocol line, which leaves room for the request around
+ * them. A larger whole write is sent as its first rows and `insert`
+ * patches of the rest; a larger patch as several patches, each applying on
+ * the one before (the player's doc/architecture/large-lists.md §4).
+ */
+export declare const CHUNK_BYTES: number;
+/** The bytes a row adds to a write (its JSON and a separator). */
+export declare const rowBytes: (row: unknown) => number;
+/**
+ * How many of the first rows (by their sizes, `rowBytes`) fit in `budget`
+ * bytes; at least one when there are rows (a row over the budget alone is
+ * left to the player's limits).
+ */
+export declare function prefixWithin(sizes: readonly number[], budget: number): number;
+/** A wire operation (`set` and `insert` carry rows). */
+export type WireOp = {
+    op: "set";
+    at: number;
+    row: unknown;
+} | {
+    op: "insert";
+    at: number;
+    rows: unknown[];
+} | {
+    op: "remove";
+    at: number;
+    count: number;
+} | {
+    op: "move";
+    from: number;
+    count: number;
+    to: number;
+};
+/**
+ * `ops` as consecutive patches of at most {@link CHUNK_BYTES} of rows and
+ * {@link PATCH_OPS} operations each, in order: applying them one after the
+ * other gives what `ops` give. An `insert` of more rows than fit is split
+ * into inserts of consecutive runs.
+ */
+export declare function chunkOps<T extends WireOp>(ops: readonly T[]): T[][];
+/** The bytes a row already in JSON adds to a write (and a separator). */
+export declare const jsonBytes: (json: string) => number;

package/dist/plugin/patch.js

@@ -9,6 +9,12 @@ import { UI_VALUE_LIMITS } from "./values.js";
 export const PATCH_FEATURE = "ui.patch";
 /** The most operations one patch carries (the player's `MAX_PATCH_OPS`). */
 export const PATCH_OPS = 1024;
+/**
+ * The most operations one diff plans (SDK 1.5.46): its patch is sent as
+ * several of at most {@link PATCH_OPS} each (`chunkOps`); more is sent whole
+ * (in parts, which the player writes at once).
+ */
+export const DIFF_OPS = 16 * PATCH_OPS;
 /**
  * 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.
@@ -159,7 +165,8 @@ function increasing(values) {
 }
 /**
  * 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
+ * than {@link DIFF_OPS} would be needed, or more than {@link PATCH_OPS}
+ * moves), 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.
  */
@@ -168,7 +175,7 @@ export function diff(old, next) {
     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;
+    return ops && ops.length <= DIFF_OPS ? { ops, from } : null;
 }
 function byIndex(old, next, from) {
     const min = Math.min(old.length, next.length);
@@ -236,7 +243,7 @@ function keyed(oldEnc, oldKeys, newEnc, newKeys, from) {
         }
         else
             ops.push({ op: "remove", at: i, count: 1 });
-        if (ops.length > PATCH_OPS)
+        if (ops.length > DIFF_OPS)
             return null;
     }
     for (let i = p; i < oldEnd; i++)
@@ -248,7 +255,10 @@ function keyed(oldEnc, oldKeys, newEnc, newKeys, from) {
     // 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)
+    // Moves cost a search each: at most PATCH_OPS of them.
+    if (kept.length - stay.size > PATCH_OPS)
+        return null;
+    if (kept.length - stay.size + ops.length > DIFF_OPS)
         return null;
     const stays = new Set();
     for (const index of stay)
@@ -281,13 +291,13 @@ function keyed(oldEnc, oldKeys, newEnc, newKeys, from) {
             last.rows.push(j);
         else
             ops.push({ op: "insert", at: j, rows: [j] });
-        if (ops.length > PATCH_OPS)
+        if (ops.length > DIFF_OPS)
             return null;
     }
     sets.sort((a, b) => a.at - b.at);
     for (const set of sets) {
         ops.push(set);
-        if (ops.length > PATCH_OPS)
+        if (ops.length > DIFF_OPS)
             return null;
     }
     return ops;
@@ -335,3 +345,91 @@ export function applyOps(rows, ops) {
         }
     return out;
 }
+/**
+ * The bytes of rows one write carries at most (SDK 1.5.46, player 0.6.0):
+ * half the 1 MiB protocol line, which leaves room for the request around
+ * them. A larger whole write is sent as its first rows and `insert`
+ * patches of the rest; a larger patch as several patches, each applying on
+ * the one before (the player's doc/architecture/large-lists.md §4).
+ */
+export const CHUNK_BYTES = 512 * 1024;
+/** About what an operation adds to a request besides its rows. */
+const OP_BYTES = 64;
+/** UTF-8 bytes of `text` (JSON of a row), without encoding it. */
+function utf8Bytes(text) {
+    let bytes = text.length;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code >= 0x80)
+            bytes += code >= 0x800 && (code < 0xd800 || code > 0xdfff) ? 2 : 1;
+    }
+    return bytes;
+}
+/** The bytes a row adds to a write (its JSON and a separator). */
+export const rowBytes = (row) => utf8Bytes(JSON.stringify(row) ?? "null") + 1;
+/**
+ * How many of the first rows (by their sizes, `rowBytes`) fit in `budget`
+ * bytes; at least one when there are rows (a row over the budget alone is
+ * left to the player's limits).
+ */
+export function prefixWithin(sizes, budget) {
+    let used = 0;
+    for (let i = 0; i < sizes.length; i++) {
+        used += sizes[i];
+        if (used > budget)
+            return Math.max(i, 1);
+    }
+    return sizes.length;
+}
+/**
+ * `ops` as consecutive patches of at most {@link CHUNK_BYTES} of rows and
+ * {@link PATCH_OPS} operations each, in order: applying them one after the
+ * other gives what `ops` give. An `insert` of more rows than fit is split
+ * into inserts of consecutive runs.
+ */
+export function chunkOps(ops) {
+    const groups = [];
+    let group = [];
+    let bytes = 0;
+    const push = (op, size) => {
+        if (group.length &&
+            (bytes + size > CHUNK_BYTES || group.length >= PATCH_OPS)) {
+            groups.push(group);
+            group = [];
+            bytes = 0;
+        }
+        group.push(op);
+        bytes += size;
+    };
+    for (const op of ops) {
+        if (op.op !== "insert") {
+            push(op, OP_BYTES + (op.op === "set" ? rowBytes(op.row) : 0));
+            continue;
+        }
+        const sizes = op.rows.map(rowBytes);
+        let start = 0;
+        while (start < sizes.length) {
+            const room = Math.max(CHUNK_BYTES - bytes - OP_BYTES, 0);
+            let count = prefixWithin(sizes.slice(start), room);
+            // Nothing fits beside this group's rows: the run starts a new patch.
+            if (room === 0 ||
+                sizes.slice(start, start + count).reduce((a, b) => a + b, 0) > room) {
+                if (group.length) {
+                    groups.push(group);
+                    group = [];
+                    bytes = 0;
+                }
+                count = prefixWithin(sizes.slice(start), CHUNK_BYTES - OP_BYTES);
+            }
+            const rows = op.rows.slice(start, start + count);
+            const size = OP_BYTES + sizes.slice(start, start + count).reduce((a, b) => a + b, 0);
+            push({ op: "insert", at: op.at + start, rows }, size);
+            start += count;
+        }
+    }
+    if (group.length)
+        groups.push(group);
+    return groups;
+}
+/** The bytes a row already in JSON adds to a write (and a separator). */
+export const jsonBytes = (json) => utf8Bytes(json) + 1;

package/dist/plugin/testing.js

@@ -935,10 +935,15 @@ export class TestHost {
      * view and property (none: 0, the initial properties).
      */
     #writes = new Map();
+    /** The parts of a whole value held until its last part, by view and property. */
+    #parts = new Map();
     #resetWrites(view) {
         for (const slot of [...this.#writes.keys()])
             if (slot.startsWith(`${view}\u0000`))
                 this.#writes.delete(slot);
+        for (const slot of [...this.#parts.keys()])
+            if (slot.startsWith(`${view}\u0000`))
+                this.#parts.delete(slot);
     }
     /**
      * A property write as the player takes it, returning the value the
@@ -950,6 +955,44 @@ export class TestHost {
     #write(view, property, p, current) {
         const slot = `${view}\u0000${property}`;
         const patch = p.patch;
+        // A whole array sent in parts (player 0.6.0, SDK 1.5.46): every part but
+        // the last carries `more`; the player holds them and writes the whole
+        // value at the last, as here (`undefined`: held, nothing shown yet).
+        const more = p.more === true;
+        const held = this.#parts.get(slot);
+        this.#parts.delete(slot);
+        if (more && patch === undefined) {
+            const rows = this.#shownValues(p.value);
+            if (!Array.isArray(rows))
+                throw new HostError("invalid", "a value sent in parts is an array");
+            noMarkdownParts(rows);
+            this.#checkValues({ [property]: rows });
+            this.#parts.set(slot, {
+                seq: typeof p.seq === "number" ? p.seq : 0,
+                rows,
+            });
+            return undefined;
+        }
+        if (patch !== undefined && held && patch.base === held.seq) {
+            const ops = patchOps(patch.ops, held.rows.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);
+            noMarkdownParts(resolved.flatMap((op) => op.op === "set" ? [op.row] : op.op === "insert" ? op.rows : []));
+            const rows = applyOps(held.rows, resolved);
+            this.#checkValues({ [property]: rows });
+            if (more) {
+                this.#parts.set(slot, { seq: patch.seq, rows });
+                return undefined;
+            }
+            this.#seeImages([rows]);
+            this.#writes.set(slot, patch.seq);
+            return rows;
+        }
+        if (patch !== undefined && more)
+            throw new HostError("stale", "the property changed since the write this patch applies on; send the whole value");
         if (patch === undefined) {
             const value = this.#shownValues(p.value);
             this.#checkValues({ [property]: value });
@@ -2211,7 +2254,7 @@ export class TestHost {
                 ["Playback", "Previous"],
                 202,
                 "domain",
-                ["PageUp", "Mouse:X1"],
+                ["PageUp", "Mouse:X2"],
                 false,
             ],
             [
@@ -2219,7 +2262,7 @@ export class TestHost {
                 ["Playback", "Next"],
                 203,
                 "domain",
-                ["PageDown", "Mouse:X2"],
+                ["PageDown", "Mouse:X1"],
                 false,
             ],
             [
@@ -3899,7 +3942,10 @@ export class TestHost {
             if (!window)
                 throw new HostError("missing", "view not found");
             const property = String(p.property);
-            window.props[property] = this.#write(`w:${String(p.id)}`, property, p, window.props[property]);
+            const next = this.#write(`w:${String(p.id)}`, property, p, window.props[property]);
+            // A part of a value sent in parts is held until the last (player 0.6.0).
+            if (next !== undefined)
+                window.props[property] = next;
         },
         "ui.show": (p) => {
             const window = this.windows.get(String(p.id));
@@ -4202,7 +4248,7 @@ export class TestHost {
                     throw new HostError("invalid", "seconds must be 0.1..3600 in tenths");
                 seconds = p.seconds;
             }
-            // SDK 1.5.21: the main window's Toggle Fullscreen, like Enter: in when
+            // SDK 1.5.21: the main window's Toggle Fullscreen, like Escape: in when
             // windowed, out when fullscreen, then `window.state`.
             if (p.action === "fullscreen") {
                 this.coreRuns.push("fullscreen");
@@ -4260,7 +4306,10 @@ export class TestHost {
         "ui.setMount": (p) => {
             const panel = this.mounted();
             const property = String(p.property);
-            panel.props[property] = this.#write("$mount", property, p, panel.props[property]);
+            const next = this.#write("$mount", property, p, panel.props[property]);
+            // A part of a value sent in parts is held until the last (player 0.6.0).
+            if (next !== undefined)
+                panel.props[property] = next;
         },
         "timeline.marks": () => ({ marks: this.timeline.marks }),
         "drops.provide": (p) => {
@@ -4323,7 +4372,10 @@ export class TestHost {
             if (!page)
                 throw new HostError("missing", "page not registered");
             const property = String(p.property);
-            page.props[property] = this.#write(`$settings:${String(p.id)}`, property, p, page.props[property]);
+            const next = this.#write(`$settings:${String(p.id)}`, property, p, page.props[property]);
+            // A part of a value sent in parts is held until the last (player 0.6.0).
+            if (next !== undefined)
+                page.props[property] = next;
         },
         "settings.unregister": (p) => {
             this.settings.pages.delete(String(p.id));
@@ -5352,6 +5404,11 @@ export async function startPlugin(activate, options = {}) {
  * before; at most {@link PATCH_OPS}; the result at most
  * `UI_VALUE_LIMITS.arrayRows` rows.
  */
+/** The player takes no Markdown documents in parts of a value (`invalid`). */
+function noMarkdownParts(rows) {
+    if (JSON.stringify(rows).includes('"$vestraMarkdown"'))
+        throw new HostError("invalid", "a value sent in parts holds no Markdown documents");
+}
 function patchOps(ops, length) {
     if (!Array.isArray(ops))
         throw new HostError("invalid", "patch.ops requires an array");

package/dist/plugin/types.d.ts

@@ -999,9 +999,12 @@ export interface CommandOptions {
      * `Home`, `End`, `PageUp`, `PageDown`, `ArrowLeft`/`Right`/`Up`/`Down`,
      * `Plus`, any other single symbol as typed (`">"`, not `"Shift+."`),
      * `Numpad0`–`Numpad9`, `NumpadPlus`, `NumpadMinus`, `NumpadMultiply`,
-     * `NumpadDivide`, `NumpadEnter`, `NumpadDecimal`, and the video-area mouse
+     * `NumpadDivide`, `NumpadEnter`, `NumpadDecimal`, the video-area mouse
      * inputs `Mouse:LeftClick`, `Mouse:LeftDoubleClick[:LeftHalf|:RightHalf]`,
-     * `Mouse:MiddleClick`, `Mouse:X1`, `Mouse:X2`, `Mouse:WheelUp`/`Down`/`Left`/`Right`.
+     * `Mouse:MiddleClick`, `Mouse:WheelUp`/`Down`/`Left`/`Right`, and the side
+     * buttons `Mouse:X1` (back), `Mouse:X2` (forward), from 0.6.0 on anywhere
+     * in the main window or the floating sidebar window, except while a menu
+     * is open.
      *
      * Platforms: on macOS `Ctrl+X` fires for both ⌃X and ⌘X while `Cmd+X`
      * means ⌘X only; on Windows `Cmd` is the Windows logo key, so write
@@ -1384,20 +1387,23 @@ export interface MarkdownOptions {
  * thumbnails.
  *
  * Limits per value (`UI_VALUE_LIMITS` in `@vestra-player/sdk/testing`,
- * player 0.4.3; older players: 4096 values and 1024 rows): nesting depth 8,
- * 16384 values in total (every array, object, string, number, boolean and
- * null counts, the value itself included; a document or an image is one), 4096 rows
- * per array, 64 KiB per string or field name and 1 MiB of text in total,
- * field names and the text of its Markdown documents included (256 KB per
- * document). A list of rows with 8 fields is 9 values per row, so about
- * 1800 rows fit. The whole request must also fit the player's 1 MiB
- * message. A value over a limit is refused with code `limit` and the
- * property keeps what it showed (see {@link View.set}); `TestHost` refuses
- * it the same way.
- *
- * The limits bound the work of one write, not the size of your data: for
- * a list that can grow without bound, send the rows near the view and the
- * row count, and move that window as the user scrolls.
+ * player 0.6.0; players 0.4.3 to 0.5: 16384 values, 4096 rows, 1 MiB of
+ * text): nesting depth 8, 1,048,576 values in total (every array, object,
+ * string, number, boolean and null counts, the value itself included; a
+ * document or an image is one), 100,000 rows per array, 64 KiB per string
+ * or field name and 32 MiB of text in total, field names and the text of
+ * its Markdown documents included (256 KB per document). A list of rows
+ * with 13 fields is 14 values per row, so 50,000 such rows fit. An array
+ * property larger than one 1 MiB request is sent in parts (SDK 1.5.46, a
+ * player that takes row patches); only the top-level array is split, so
+ * any other value, and each row, must fit in one request (a row of more
+ * than 512 KiB is refused with `limit`). A value over a limit is refused
+ * with code
+ * `limit` and the property keeps what it showed (see {@link View.set});
+ * `TestHost` refuses it the same way.
+ *
+ * Bind a whole list and draw it with a Slint `ListView`, which builds only
+ * the rows on screen; the SDK sends what changed (row patches).
  *
  * @since 1.0.0
  * @category UI
@@ -6058,13 +6064,13 @@ export interface Player {
  * | --- | --- | --- |
  * | `stop` | F4 | close the source |
  * | `play-pause` | Space, a left click on the video (player 0.5.2) | pause / resume, replay after the end |
- * | `previous` / `next` | PageUp, Mouse:X1 / PageDown, Mouse:X2 | ask the sequence provider |
+ * | `previous` / `next` | PageUp, Mouse:X2 / PageDown, Mouse:X1 (from 0.6.0; up to 0.5.x X1 was previous and X2 next) | ask the sequence provider |
  * | `frame-back` / `frame-forward` | D / F | `player.step("frame", …)` |
  * | `seek-backward` / `seek-forward` | ← / → | relative seek by `setStepSeek` seconds (or `host.run`'s `seconds`), exact or to keyframes as `setStepSeek` says |
  * | `rate-normal`, `rate-down`, `rate-up` | Z, X, C | 1×, ±0.1 within 0.25–4 |
  * | `volume-up` / `volume-down` | ↑ / ↓, wheel | ±5 (`volume-up` stops at 100) |
  * | `mute` | M | toggle mute |
- * | `fullscreen` | Enter, Alt+Enter, F11 | toggle the main window's fullscreen: enter it when windowed, leave it when fullscreen, as the Toggle Fullscreen command does (SDK 1.5.21, player 0.5.2; `unavailable` when the player has no window) |
+ * | `fullscreen` | Escape (from 0.6.0; up to 0.5.x Enter, Alt+Enter, F11) | toggle the main window's fullscreen: enter it when windowed, leave it when fullscreen, as the Toggle Fullscreen command does (SDK 1.5.21, player 0.5.2; `unavailable` when the player has no window) |
  *
  * In the binding overlay their keys are `host/<action>`. `fullscreen`
  * changes no playback state: read the result from `window.state.fullscreen`

package/dist/plugin/ui.d.ts

@@ -32,9 +32,15 @@ export declare abstract class ViewBase implements View {
     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.
+     * property keeps its default) and reported, like a failed write. With a
+     * player that takes row patches, the arrays of one request carry at most
+     * {@link CHUNK_BYTES} of rows together (SDK 1.5.46): an array over that
+     * goes with its first rows, and the first flush sends the rest as patches.
+     * An array over the value limits is refused here, as the player would
+     * refuse it whole: left out and reported (a panel, a settings page), or,
+     * with `refuse` (a window's `show`), thrown.
      */
-    protected wired(values: Record<string, PropValue>): Record<string, Json>;
+    protected wired(values: Record<string, PropValue>, refuse?: boolean): Record<string, Json>;
     on<A extends Json[]>(callback: string, handler: (...args: A) => unknown): Disposable;
     set(props: Props): void;
     bind(props: () => Props): Disposable;