@vestra-player/sdk 1.5.45 → 1.5.46

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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/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 });
@@ -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));
@@ -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

@@ -1384,20 +1384,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

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;

package/dist/plugin/ui.js

@@ -7,7 +7,8 @@ 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";
+import { countRow, diff, keyOf, CHUNK_BYTES, chunkOps, PATCH_FEATURE, prefixWithin, jsonBytes, rowBytes, replay, withinLimits, } from "./patch.js";
+import { UI_VALUE_LIMITS, valueLimitProblem } from "./values.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]));
@@ -110,6 +111,26 @@ function sentOf(value, patches) {
     }
     return { kind: "json", enc: JSON.stringify(value) };
 }
+/**
+ * A write sent in parts stopped because its view closed or showed its
+ * initial properties again: not a failure.
+ */
+class Abandoned extends Error {
+}
+/** The wire key of a Markdown document: rows holding one are never sent in parts. */ const MARKDOWN_KEY = '"$vestraMarkdown"';
+/** A row larger than one request can carry (`limit`). */
+const rowTooLarge = (key, bytes) => new HostError("limit", `${key}: a row of ${bytes} bytes is larger than one request takes (${CHUNK_BYTES} bytes)`);
+/** Refuse a patch carrying a row larger than one request, before sending it. */
+function tooLarge(key, ops) {
+    for (const op of ops) {
+        const rows = op.op === "set" ? [op.row] : op.op === "insert" ? op.rows : [];
+        for (const row of rows) {
+            const bytes = rowBytes(row);
+            if (bytes > CHUNK_BYTES)
+                throw rowTooLarge(key, bytes);
+        }
+    }
+}
 /**
  * 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:
@@ -194,6 +215,8 @@ export class ViewBase {
      */
     #stales = new Map();
     #seq = 0;
+    /** Counts the times the view showed its initial properties (`shown`). */
+    #generation = 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. */
@@ -215,18 +238,51 @@ export class ViewBase {
     }
     /**
      * 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.
      */
-    wired(values) {
+    wired(values, refuse = false) {
         const out = {};
+        let room = CHUNK_BYTES;
         for (const [key, value] of Object.entries(values)) {
+            let wire;
             try {
-                out[key] = wireValue(value);
+                wire = wireValue(value);
             }
             catch (error) {
                 this.#failed.set(key, JSON.stringify(value));
                 this.scope.report(error);
+                continue;
+            }
+            if (this.#patches && Array.isArray(wire)) {
+                const sizes = wire.map(rowBytes);
+                const total = sizes.reduce((a, b) => a + b, 0);
+                if (total > room && !JSON.stringify(wire).includes(MARKDOWN_KEY)) {
+                    const largest = sizes.reduce((a, b) => Math.max(a, b), 0);
+                    const problem = valueLimitProblem(wire);
+                    if (problem || largest > CHUNK_BYTES) {
+                        const error = problem
+                            ? new HostError("limit", `${key}: ${problem}`)
+                            : rowTooLarge(key, largest);
+                        if (refuse)
+                            throw error;
+                        this.#failed.set(key, JSON.stringify(value));
+                        this.scope.report(error);
+                        continue;
+                    }
+                    const count = room > 0 ? prefixWithin(sizes, room) : 0;
+                    wire = wire.slice(0, count);
+                    room -= sizes.slice(0, count).reduce((a, b) => a + b, 0);
+                }
+                else
+                    room -= total;
             }
+            out[key] = wire;
         }
         return out;
     }
@@ -289,6 +345,7 @@ export class ViewBase {
     }
     /** The host already shows these values (e.g. sent as initial properties). */
     shown(values) {
+        this.#generation++;
         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]) : []);
@@ -354,7 +411,10 @@ export class ViewBase {
      * 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.
+     * of the property is whole. A write larger than one request
+     * ({@link CHUNK_BYTES} of rows, SDK 1.5.46) is sent in parts: a whole
+     * array as its first rows and `insert` patches of the rest, a patch as
+     * several, each applying on the one before.
      */
     async #send(pending) {
         const { key, value } = pending;
@@ -362,34 +422,121 @@ export class ViewBase {
             await this.write(key, { value: wireValue(value) });
             return pending.sent();
         }
+        const generation = this.#generation;
         const base = this.#bases.get(key);
         this.#bases.delete(key);
         const sent = this.#sent.get(key);
-        const plan = base !== undefined &&
+        let plan = base !== undefined &&
             sent?.kind === "rows" &&
             pending.rows &&
             (this.#stales.get(key) ?? 0) < 2
             ? rowPatch(sent.rows, pending.rows, value)
             : null;
+        // A patch sent in several never passes the row limit midway (the diff
+        // removes before it inserts; checked anyway); otherwise whole.
+        if (plan && sent?.kind === "rows") {
+            let length = sent.rows.enc.length;
+            for (const op of plan.ops) {
+                if (op.op === "insert")
+                    length += op.rows.length;
+                else if (op.op === "remove")
+                    length -= op.count;
+                if (length > UI_VALUE_LIMITS.arrayRows) {
+                    plan = null;
+                    break;
+                }
+            }
+        }
         if (plan) {
+            tooLarge(key, plan.ops);
+            const [first, ...rest] = chunkOps(plan.ops);
             const seq = ++this.#seq;
+            let applied = false;
             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);
+                await this.write(key, { patch: { base: base, seq, ops: first } });
+                applied = true;
             }
             catch (error) {
                 if (!(error instanceof HostError && error.code === "stale"))
                     throw error;
                 this.#stales.set(key, (this.#stales.get(key) ?? 0) + 1);
             }
+            if (applied) {
+                this.#stales.delete(key);
+                await this.#parts(key, seq, rest, false, generation);
+                return pending.sent(plan.counts);
+            }
         }
         const seq = ++this.#seq;
+        // Rows holding Markdown documents go whole, as before: the player
+        // merges documents in place and takes no parts of them.
+        if (Array.isArray(value) &&
+            pending.rows &&
+            !pending.rows.enc.some((row) => row.includes(MARKDOWN_KEY))) {
+            const sizes = pending.rows.enc.map(jsonBytes);
+            const count = prefixWithin(sizes, CHUNK_BYTES);
+            if (count < value.length) {
+                const rows = value;
+                // Over the limits, or a row larger than one request: refused here,
+                // as the player would refuse the whole value, before any part is
+                // sent (a part refused midway would leave the list half sent).
+                const problem = valueLimitProblem(wireValue(value));
+                if (problem)
+                    throw new HostError("limit", `${key}: ${problem}`);
+                const largest = sizes.reduce((a, b) => Math.max(a, b), 0);
+                if (largest > CHUNK_BYTES)
+                    throw rowTooLarge(key, largest);
+                // Every part but the last carries `more`: the player holds them
+                // and writes the whole value at the last, so a list it shows is
+                // written once (player 0.6.0).
+                await this.write(key, {
+                    value: wireValue(rows.slice(0, count)),
+                    seq,
+                    more: true,
+                });
+                const insert = {
+                    op: "insert",
+                    at: count,
+                    rows: rows.slice(count).map((row) => wireValue(row ?? null)),
+                };
+                await this.#parts(key, seq, chunkOps([insert]), true, generation);
+                return pending.sent();
+            }
+        }
         await this.write(key, { value: wireValue(value), seq });
         this.#bases.set(key, seq);
         return pending.sent();
     }
+    /**
+     * The rest of a write sent in parts: each patch applies on the one
+     * before (`base`), and the property's base is the last one's; with
+     * `more`, every part but the last says so. A failure leaves no base: the
+     * next write of the property is whole. When the view closed or showed its
+     * initial properties again meanwhile (`generation`), the rest is dropped
+     * quietly ({@link Abandoned}): the view's next flush sends what it shows.
+     */
+    async #parts(key, base, groups, more, generation) {
+        let last = base;
+        for (const [i, ops] of groups.entries()) {
+            if (!this.live() || this.#generation !== generation)
+                throw new Abandoned();
+            const seq = ++this.#seq;
+            try {
+                await this.write(key, {
+                    patch: { base: last, seq, ops },
+                    ...(more && i < groups.length - 1 ? { more: true } : {}),
+                });
+            }
+            catch (error) {
+                // Refused because the view went meanwhile: not a failure.
+                if (!this.live() || this.#generation !== generation)
+                    throw new Abandoned();
+                throw error;
+            }
+            last = seq;
+        }
+        this.#bases.set(key, last);
+    }
     /**
      * 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
@@ -431,6 +578,13 @@ export class ViewBase {
                             this.#broken = false;
                         }
                         catch (error) {
+                            // The view closed or showed its initial properties again while
+                            // a write was sent in parts: nothing failed (the next flush
+                            // sends what the view shows).
+                            if (error instanceof Abandoned) {
+                                queueMicrotask(() => this.flush());
+                                return;
+                            }
                             failed = true;
                             // Report the start of a failing streak only.
                             if (!this.#broken)
@@ -530,7 +684,7 @@ class WindowHandle extends ViewBase {
             const ui = this.scope.runtime.host.ui;
             if (this.#opened)
                 return ui.show(this.#id, true);
-            const initial = this.wired(this.snapshot());
+            const initial = this.wired(this.snapshot(), true);
             await ui.open(this.#id, this.#file, initial, [...this.handlers.keys()]);
             this.#opened = true;
             this.shown(initial);

package/dist/plugin/values.d.ts

@@ -12,41 +12,26 @@ import type { Json } from "../wire.ts";
  * makes `Window.show` reject; a panel or settings page opens without it and
  * the failure goes to the plugin's `onError`.
  *
- * They bound the work one write costs the player's interface thread; they
- * are not meant as list sizes to aim for. A list that can grow without
- * bound (a playlist, a history) should send the rows near the view and say
- * how many there are, not the whole list.
+ * Since player 0.6.0 (SDK 1.5.46) they allow a whole list: a plugin binds
+ * all of its rows (a playlist of 50,000 entries fits) and the view draws
+ * them with a Slint `ListView`, which builds only the rows on screen. The
+ * SDK sends a changed array as row patches, and an array larger than one
+ * request (about 512 KiB of rows) as its first rows followed by `insert`
+ * patches of the rest; the player converts large writes off its interface
+ * thread. Before player 0.6.0 the limits were 4,096 rows, 16,384 values and
+ * 1 MiB of text, so a long list had to be sent as a window of rows.
+ *
+ * In a row, `null` where the view declares an `image` shows no picture
+ * (player 0.6.0): rows without a thumbnail need no placeholder image.
+ *
+ * @example Bind a whole list
+ * The view draws every row with a `ListView`; the SDK sends what changed.
  *
- * @example Send a long playlist as a window of rows
- * A list view shows any number of entries while each write stays small:
- * the plugin sends only the rows around the scroll position plus the total,
- * and the view reports where it scrolled to. After the `scrolled` handler
- * returns, the SDK evaluates the `bind` function again and sends the new
- * window. Each row object and each of its fields count as one value toward
- * `values`, and so does the array holding them.
  * ```ts
- * declare const entries: { title: string; duration: number }[];
- * import type { View } from "@vestra-player/sdk";
+ * declare const entries: { id: string; title: string; duration: string }[];
  * declare const list: View;
  * // ---cut---
- * import { UI_VALUE_LIMITS } from "@vestra-player/sdk/testing";
- *
- * // 200 rows, or fewer if the limits were smaller: 2 fields per row make
- * // 3 values (the row and its fields), plus 1 for the array.
- * const size = Math.min(
- *   200,
- *   UI_VALUE_LIMITS.arrayRows,
- *   Math.floor((UI_VALUE_LIMITS.values - 1) / 3),
- * );
- * let first = 0;
- * list.bind(() => ({
- *   total: entries.length,
- *   rows: entries.slice(first, first + size),
- * }));
- * // The Slint view reports its first visible row; the window follows it.
- * list.on("scrolled", (row: number) => {
- *   first = Math.max(0, row - Math.floor(size / 2));
- * });
+ * list.bind(() => ({ rows: entries.map((e) => ({ ...e, selected: false })) }));
  * ```
  *
  * @since 1.5.10
@@ -59,16 +44,16 @@ export declare const UI_VALUE_LIMITS: {
     /**
      * Values in all, counting every array, object, string, number, boolean
      * and null, the value itself included; a Markdown document is one
-     * (16384).
+     * (1,048,576; 16,384 before player 0.6.0).
      */
-    readonly values: 16384;
-    /** Rows of one array (4096). */
-    readonly arrayRows: 4096;
+    readonly values: number;
+    /** Rows of one array (100,000; 4,096 before player 0.6.0). */
+    readonly arrayRows: 100000;
     /** UTF-8 bytes of one string or object field name (64 KiB). */
     readonly stringBytes: number;
     /**
      * UTF-8 bytes of all strings and field names together, the text of the
-     * value's Markdown documents included (1 MiB).
+     * value's Markdown documents included (32 MiB; 1 MiB before player 0.6.0).
      */
     readonly textBytes: number;
 };

package/dist/plugin/values.js

@@ -10,41 +10,26 @@
  * makes `Window.show` reject; a panel or settings page opens without it and
  * the failure goes to the plugin's `onError`.
  *
- * They bound the work one write costs the player's interface thread; they
- * are not meant as list sizes to aim for. A list that can grow without
- * bound (a playlist, a history) should send the rows near the view and say
- * how many there are, not the whole list.
+ * Since player 0.6.0 (SDK 1.5.46) they allow a whole list: a plugin binds
+ * all of its rows (a playlist of 50,000 entries fits) and the view draws
+ * them with a Slint `ListView`, which builds only the rows on screen. The
+ * SDK sends a changed array as row patches, and an array larger than one
+ * request (about 512 KiB of rows) as its first rows followed by `insert`
+ * patches of the rest; the player converts large writes off its interface
+ * thread. Before player 0.6.0 the limits were 4,096 rows, 16,384 values and
+ * 1 MiB of text, so a long list had to be sent as a window of rows.
+ *
+ * In a row, `null` where the view declares an `image` shows no picture
+ * (player 0.6.0): rows without a thumbnail need no placeholder image.
+ *
+ * @example Bind a whole list
+ * The view draws every row with a `ListView`; the SDK sends what changed.
  *
- * @example Send a long playlist as a window of rows
- * A list view shows any number of entries while each write stays small:
- * the plugin sends only the rows around the scroll position plus the total,
- * and the view reports where it scrolled to. After the `scrolled` handler
- * returns, the SDK evaluates the `bind` function again and sends the new
- * window. Each row object and each of its fields count as one value toward
- * `values`, and so does the array holding them.
  * ```ts
- * declare const entries: { title: string; duration: number }[];
- * import type { View } from "@vestra-player/sdk";
+ * declare const entries: { id: string; title: string; duration: string }[];
  * declare const list: View;
  * // ---cut---
- * import { UI_VALUE_LIMITS } from "@vestra-player/sdk/testing";
- *
- * // 200 rows, or fewer if the limits were smaller: 2 fields per row make
- * // 3 values (the row and its fields), plus 1 for the array.
- * const size = Math.min(
- *   200,
- *   UI_VALUE_LIMITS.arrayRows,
- *   Math.floor((UI_VALUE_LIMITS.values - 1) / 3),
- * );
- * let first = 0;
- * list.bind(() => ({
- *   total: entries.length,
- *   rows: entries.slice(first, first + size),
- * }));
- * // The Slint view reports its first visible row; the window follows it.
- * list.on("scrolled", (row: number) => {
- *   first = Math.max(0, row - Math.floor(size / 2));
- * });
+ * list.bind(() => ({ rows: entries.map((e) => ({ ...e, selected: false })) }));
  * ```
  *
  * @since 1.5.10
@@ -57,18 +42,18 @@ export const UI_VALUE_LIMITS = {
     /**
      * Values in all, counting every array, object, string, number, boolean
      * and null, the value itself included; a Markdown document is one
-     * (16384).
+     * (1,048,576; 16,384 before player 0.6.0).
      */
-    values: 16384,
-    /** Rows of one array (4096). */
-    arrayRows: 4096,
+    values: 1024 * 1024,
+    /** Rows of one array (100,000; 4,096 before player 0.6.0). */
+    arrayRows: 100_000,
     /** UTF-8 bytes of one string or object field name (64 KiB). */
     stringBytes: 64 * 1024,
     /**
      * UTF-8 bytes of all strings and field names together, the text of the
-     * value's Markdown documents included (1 MiB).
+     * value's Markdown documents included (32 MiB; 1 MiB before player 0.6.0).
      */
-    textBytes: 1024 * 1024,
+    textBytes: 32 * 1024 * 1024,
 };
 const L = UI_VALUE_LIMITS;
 const bytes = (text) => Buffer.byteLength(text, "utf8");

package/dist/wire.d.ts

@@ -88,12 +88,15 @@ export type RowOp = {
 export type PropertyWrite = {
     value: Json;
     seq?: number;
+    more?: boolean;
 } | {
     patch: {
         base: number;
         seq: number;
         ops: RowOp[];
     };
+    /** A part of a whole value sent in parts, not the last (player 0.6.0). */
+    more?: boolean;
 };
 /**
  * A definite refusal from the player (or the plugin runner), with a stable

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.45: full reference
+# @vestra-player/sdk 1.5.46: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -2284,6 +2284,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.20 | VideoShaders |
 | 0.5.21 | Scope.when, When, Bindings.onChange |
 | 0.5.25 | UpscalingReason.cause, UpscalingReason.plugins, UpscalingDecodingCause, UpscalingPlugin, UpscalingVideoSize, UpscalingState.video, UpscalingState.area, UpscalingState.gpu, UpscalingState.hwdecCurrent, UpscalingState.inChain, VideoUpscaling.onChange |
+| 0.6.0 | PropValue |
 
 The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
 
@@ -2352,7 +2353,7 @@ The check follows types, not names: `plugin.player.seek`, `const { player } = pl
 
 ## Reference: Limits
 
-The player bounds what one request may cost it. The limits are guards against runaway plugins, not sizes to aim for: a plugin that needs to come close to one usually needs a different design (send the rows near the view, not the whole list). The SDK checks the same limits before it sends a request, so a plugin's own tests hit them too (TestHost enforces them). A name in code style is a constant you can import from `@vestra-player/sdk/testing`.
+The player bounds what one request may cost it. The limits are guards against runaway plugins, not sizes to aim for. Since player 0.6.0 a whole list fits (50,000 playlist rows): bind it and draw it with a Slint `ListView` (a long list should use one: a `for` builds every row). The SDK sends row patches, and an array property larger than one request in parts (SDK 1.5.46); only a property's top-level array without Markdown documents 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`). The SDK checks the same limits before it sends a request, so a plugin's own tests hit them too (TestHost enforces them). A name in code style is a constant you can import from `@vestra-player/sdk/testing`.
 
 #### Commands
 
@@ -2380,10 +2381,10 @@ One value written to a window, panel or settings page property (View.set, View.b
 | Limit | Value | Meaning |
 | --- | --- | --- |
 | `UI_VALUE_LIMITS.depth` | 8 | Nesting depth; the value itself is depth 0. |
-| `UI_VALUE_LIMITS.values` | 16384 | Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one. |
-| `UI_VALUE_LIMITS.arrayRows` | 4096 | Rows of one array. |
+| `UI_VALUE_LIMITS.values` | 1048576 | Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one. |
+| `UI_VALUE_LIMITS.arrayRows` | 100000 | Rows of one array. |
 | `UI_VALUE_LIMITS.stringBytes` | 65536 (64 KiB) | UTF-8 bytes of one string or object field name. |
-| `UI_VALUE_LIMITS.textBytes` | 1048576 (1 MiB) | UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included. |
+| `UI_VALUE_LIMITS.textBytes` | 33554432 (32 MiB) | UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included. |
 
 #### Text values
 
@@ -5816,6 +5817,7 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [1.5.46](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1546) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. | — |
 | [1.5.45](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1545) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. | — |
 | [1.5.44](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1544) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. | — |
 | [1.5.43](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1543) | **Nobody.** Additions only, `apiVersion` stays `vestra/1`, no new capability. | — |
@@ -7102,20 +7104,23 @@ ImageOptions.maxSide for small pictures such as logos and
 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 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 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).
 
 ```ts
 type PropValue = PropData | ImageRef;
@@ -17854,53 +17859,41 @@ keeps what it showed) and reported to `Scope.onError`: a write by
 makes `Window.show` reject; a panel or settings page opens without it and
 the failure goes to the plugin's `onError`.
 
-They bound the work one write costs the player's interface thread; they
-are not meant as list sizes to aim for. A list that can grow without
-bound (a playlist, a history) should send the rows near the view and say
-how many there are, not the whole list.
+Since player 0.6.0 (SDK 1.5.46) they allow a whole list: a plugin binds
+all of its rows (a playlist of 50,000 entries fits) and the view draws
+them with a Slint `ListView`, which builds only the rows on screen. The
+SDK sends a changed array as row patches, and an array larger than one
+request (about 512 KiB of rows) as its first rows followed by `insert`
+patches of the rest; the player converts large writes off its interface
+thread. Before player 0.6.0 the limits were 4,096 rows, 16,384 values and
+1 MiB of text, so a long list had to be sent as a window of rows.
+
+In a row, `null` where the view declares an `image` shows no picture
+(player 0.6.0): rows without a thumbnail need no placeholder image.
 
 ```ts
 const UI_VALUE_LIMITS: {
   /** Nesting depth; the value itself is depth 0 (8). */
   readonly depth: 8;
-  /** Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one (16384). */
-  readonly values: 16384;
-  /** Rows of one array (4096). */
-  readonly arrayRows: 4096;
+  /**
+   * Values in all, counting every array, object, string, number, boolean and null, the value itself included; a Markdown document is one (1,048,576; 16,384 before player 0.6.0).
+   */
+  readonly values: number;
+  /** Rows of one array (100,000; 4,096 before player 0.6.0). */
+  readonly arrayRows: 100000;
   /** UTF-8 bytes of one string or object field name (64 KiB). */
   readonly stringBytes: number;
-  /** UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included (1 MiB). */
+  /** UTF-8 bytes of all strings and field names together, the text of the value's Markdown documents included (32 MiB; 1 MiB before player 0.6.0). */
   readonly textBytes: number;
 };
 ```
 
-Example: Send a long playlist as a window of rows
+Example: Bind a whole list
 
-A list view shows any number of entries while each write stays small:
-the plugin sends only the rows around the scroll position plus the total,
-and the view reports where it scrolled to. After the `scrolled` handler
-returns, the SDK evaluates the `bind` function again and sends the new
-window. Each row object and each of its fields count as one value toward
-`values`, and so does the array holding them.
-```ts
-import { UI_VALUE_LIMITS } from "@vestra-player/sdk/testing";
+The view draws every row with a `ListView`; the SDK sends what changed.
 
-// 200 rows, or fewer if the limits were smaller: 2 fields per row make
-// 3 values (the row and its fields), plus 1 for the array.
-const size = Math.min(
-  200,
-  UI_VALUE_LIMITS.arrayRows,
-  Math.floor((UI_VALUE_LIMITS.values - 1) / 3),
-);
-let first = 0;
-list.bind(() => ({
-  total: entries.length,
-  rows: entries.slice(first, first + size),
-}));
-// The Slint view reports its first visible row; the window follows it.
-list.on("scrolled", (row: number) => {
-  first = Math.max(0, row - Math.floor(size / 2));
-});
+```ts
+list.bind(() => ({ rows: entries.map((e) => ({ ...e, selected: false })) }));
 ```
 
 ### IMAGE_LIMITS

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.45: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process (the player's built-in plugins share one). Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
+> @vestra-player/sdk 1.5.46: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process (the player's built-in plugins share one). Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
 
 **Rules**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2218–2291.
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2218–2292.
 
 **main.ts**
 
@@ -78,9 +78,9 @@ export default async function activate(plugin: Plugin) {
 - `secrets`: Secrets.get/set/delete
 - `rendering.manage`: Rendering.setPreference/restartPlayer
 - `video.upscaling`: VideoUpscaling.state/set/onChange
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2292–2352.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2293–2353.
 
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L1861–2021; TestHost: L15479.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L1861–2021; TestHost: L15484.
 
 **Command line**
 
@@ -108,40 +108,40 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player
-- Others: PluginError, llms-full.txt L5952.
+- Others: PluginError, llms-full.txt L5954.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; pages: [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–134; Add a window L135–213; Add settings and translations L214–367; Test, check, pack and publish L368–424; Write your own blur kernel L425–685
 - How-to: Control playback L686–854; Store a plugin's data L855–961; Load subtitles from a plugin L962–1074; Keep a slider responsive while dragging L1075–1262; Remember a window's state between runs L1263–1414; Offer a GPU rendering switch L1415–1540; Keep a command's state without keeping the plugin running L1541–1697; Translate a plugin L1698–1860; Test a plugin L1861–2021; Publish a plugin L2022–2123; Troubleshooting L2124–2217
-- Reference: Manifest L2218–2291; Capabilities L2292–2352; Limits L2353–2498; Commands, menus and bindings L2499–3024; Platforms L3025–3055; Theme L3056–3405; Command line L3406–3463; Error codes L3464–3511; Translations L3512–3604; Test host L3605–3791
-- Explanation: How a plugin runs L3792–3994; Commands, menus and key bindings L3995–4149; Playback state, controls and sources L4150–4309; Video and audio processing L4310–4430; Windows, panels, settings pages, dialogs and the OSD L4431–4693; GPU and software rendering L4694–4710; The player's Rust core L4711–5052; How the player runs and talks to plugins L5053–5392
-- Guidelines: Plugin rules L5393–5404; Interface guidelines L5405–5521; Menu guidelines L5522–5580
-- Upgrading: Migrate a plugin to English source text L5581–5730; Migrating off package rollback (1.5.16, removed in 1.5.17) L5731–5808; Who must change, release by release L5809–5874
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5875–15152
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15153–18027
+- Reference: Manifest L2218–2292; Capabilities L2293–2353; Limits L2354–2499; Commands, menus and bindings L2500–3025; Platforms L3026–3056; Theme L3057–3406; Command line L3407–3464; Error codes L3465–3512; Translations L3513–3605; Test host L3606–3792
+- Explanation: How a plugin runs L3793–3995; Commands, menus and key bindings L3996–4150; Playback state, controls and sources L4151–4310; Video and audio processing L4311–4431; Windows, panels, settings pages, dialogs and the OSD L4432–4694; GPU and software rendering L4695–4711; The player's Rust core L4712–5053; How the player runs and talks to plugins L5054–5393
+- Guidelines: Plugin rules L5394–5405; Interface guidelines L5406–5522; Menu guidelines L5523–5581
+- Upgrading: Migrate a plugin to English source text L5582–5731; Migrating off package rollback (1.5.16, removed in 1.5.17) L5732–5809; Who must change, release by release L5810–5876
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5877–15157
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15158–18020
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L6291, Scope L6027, PluginError L5952, Disposable L5890
-- Commands L6881; When L6478; Windows L7824; Panels L9270; Dialogs L9940; Player L10681; video: VideoFilter L11561, VideoView L11661, RenderOptions L11748, VideoShaders L11826, VideoUpscaling L12184; audio: AudioFilter L11606; Subtitles L12420; media: MediaCapture L12824; Resolvers L13054; Packages L13456; Osd L11426; Host L11268; Clipboard L13785; Power L13872; Tools L13931; Storage L14083; System L14282; Secrets L14362; window: MainWindow L9587; App L9767; Rendering L14625; Bindings L13684; Ui L7170; Timeline L9499; Drops L8517; Appearance L8598; I18n L8831; Settings L9114.
+- Plugin L6293, Scope L6029, PluginError L5954, Disposable L5892
+- Commands L6883; When L6480; Windows L7829; Panels L9275; Dialogs L9945; Player L10686; video: VideoFilter L11566, VideoView L11666, RenderOptions L11753, VideoShaders L11831, VideoUpscaling L12189; audio: AudioFilter L11611; Subtitles L12425; media: MediaCapture L12829; Resolvers L13059; Packages L13461; Osd L11431; Host L11273; Clipboard L13790; Power L13877; Tools L13936; Storage L14088; System L14287; Secrets L14367; window: MainWindow L9592; App L9772; Rendering L14630; Bindings L13689; Ui L7175; Timeline L9504; Drops L8522; Appearance L8603; I18n L8836; Settings L9119.
 
 ## Examples
 
 Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L18462–18557
-- blur: A tool window with one slider that blurs the playing video. L18558–18825
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18826–19164
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19165–19357
-- panel-menu: A sidebar panel with its own right-click menu. L19358–19572
-- menus: Radio menu items, separator groups and a menu item whose title changes. L19573–19738
-- theme-widgets: A tool window drawn with the player's theme and widgets. L19739–19908
-- markdown: A window that shows a Markdown document. L19909–20111
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L20112–20285
+- hello: The README Quick start: one menu command and an on-screen message. L18455–18550
+- blur: A tool window with one slider that blurs the playing video. L18551–18818
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18819–19157
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19158–19350
+- panel-menu: A sidebar panel with its own right-click menu. L19351–19565
+- menus: Radio menu items, separator groups and a menu item whose title changes. L19566–19731
+- theme-widgets: A tool window drawn with the player's theme and widgets. L19732–19901
+- markdown: A window that shows a Markdown document. L19902–20104
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L20105–20278
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.45",
+  "version": "1.5.46",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {