@vestra-player/sdk 1.5.44 → 1.5.46

package/dist/plugin/runtime.js

@@ -53,6 +53,39 @@ export function quiet(promise) {
     promise.catch(() => { });
     return promise;
 }
+/** Whether something that read `deps` may see a different result after `change`. */
+function affected(deps, change) {
+    for (const [key, fields] of change) {
+        const read = deps.get(key);
+        if (!read)
+            continue;
+        if (read.size === 0)
+            return true;
+        for (const field of fields)
+            if (read.has(field))
+                return true;
+    }
+    return false;
+}
+/** Add `from` to `into` (an empty set, the whole state, wins). */
+function merge(into, from) {
+    for (const [key, fields] of from) {
+        const set = into.get(key);
+        if (!set)
+            into.set(key, new Set(fields));
+        else if (set.size && fields.size)
+            for (const field of fields)
+                set.add(field);
+        else
+            set.clear();
+    }
+}
+/**
+ * The longest a binding waits for a full pass while precise passes skip
+ * it: state a plugin changes outside code the SDK runs (its own timer,
+ * without `update()`) still shows within about this long.
+ */
+export const SAFETY_PASS_MS = 1000;
 export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /** One value in flight, only the newest waiting. Each push learns its fate. */
 export class Latest {
@@ -124,6 +157,22 @@ export class Runtime {
     /** Who reads now (a command's field and where it was added). */
     #reader;
     #scheduled = false;
+    /** The next pass evaluates every binding (not only a state copy changed). */
+    #full = false;
+    /** State copy changes since the last pass (a precise pass, unless `#full`). */
+    #pending = new Map();
+    /** The change the running precise pass is for; `undefined` in a full pass. */
+    #pass;
+    /** The state copy fields read by what is being evaluated now. */
+    #deps;
+    /** Each part's reads and fields last time (`part`). */
+    #parts = new WeakMap();
+    /** A precise pass skipped something: a full pass follows (`SAFETY_PASS_MS`). */
+    #safety;
+    /** The running pass skipped a binding or a part. */
+    #skipped = false;
+    /** The plugin was disposed: no safety pass is armed any more. */
+    #stopped = false;
     #events = new Map();
     views = new Map();
     commands = new Map();
@@ -196,11 +245,12 @@ export class Runtime {
     }
     bind(evaluate) {
         const held = new Map();
-        this.#bindings.set(evaluate, held);
+        const binding = { held, deps: new Map() };
+        this.#bindings.set(evaluate, binding);
         this.invalidate();
         return {
             dispose: async () => {
-                if (this.#bindings.get(evaluate) !== held)
+                if (this.#bindings.get(evaluate) !== binding)
                     return;
                 this.#bindings.delete(evaluate);
                 for (const hold of held.values())
@@ -231,6 +281,92 @@ export class Runtime {
             return `${reader.label} is a function that reads ${read}${at}${hint}`;
         });
     }
+    /**
+     * A field of the SDK's copy of a state (`key`) is read; without `field`,
+     * the state is taken (`plugin.player.state`). What is being evaluated
+     * then depends on it: a precise pass after a change of that field runs
+     * it again.
+     */
+    depends(key, field) {
+        const deps = this.#deps;
+        if (!deps)
+            return;
+        let fields = deps.get(key);
+        if (!fields)
+            deps.set(key, (fields = new Set()));
+        if (field !== undefined)
+            fields.add(field);
+    }
+    /**
+     * Evaluate one part of the binding being evaluated (one `view.bind`
+     * function), identified by `token`. A precise pass skips it when nothing
+     * it read last time changed, and returns `undefined`; what it read then
+     * still counts for the binding.
+     */
+    part(token, read) {
+        const last = this.#parts.get(token);
+        const outerReads = this.#reads;
+        const outerDeps = this.#deps;
+        if (last && this.#pass && !affected(last.deps, this.#pass)) {
+            this.#skipped = true;
+            if (outerReads)
+                for (const [event, why] of last.reads)
+                    if (!outerReads.has(event))
+                        outerReads.set(event, why);
+            if (outerDeps)
+                merge(outerDeps, last.deps);
+            return undefined;
+        }
+        const reads = new Map();
+        const deps = new Map();
+        this.#reads = outerReads && reads;
+        this.#deps = deps;
+        try {
+            return { value: read() };
+        }
+        finally {
+            this.#reads = outerReads;
+            this.#deps = outerDeps;
+            this.#parts.set(token, { reads, deps });
+            if (outerReads)
+                for (const [event, why] of reads)
+                    if (!outerReads.has(event))
+                        outerReads.set(event, why);
+            if (outerDeps)
+                merge(outerDeps, deps);
+        }
+    }
+    /**
+     * Run plugin code (a state listener) and return the state copy fields it
+     * read; they are not counted as a binding's.
+     */
+    observe(run) {
+        const outerReads = this.#reads;
+        const outerDeps = this.#deps;
+        const deps = new Map();
+        this.#reads = undefined;
+        this.#deps = deps;
+        try {
+            return { value: run(), deps };
+        }
+        finally {
+            this.#reads = outerReads;
+            this.#deps = outerDeps;
+        }
+    }
+    /**
+     * Whether code that read `deps` while `change` was delivered needs a full
+     * pass after it: it read a field that changed, or no field of that state
+     * at all (so the SDK cannot tell what it depends on).
+     */
+    needsFull(deps, change) {
+        for (const key of change.keys()) {
+            const read = deps.get(key);
+            if (!read || read.size === 0)
+                return true;
+        }
+        return affected(deps, change);
+    }
     /**
      * Evaluate `read` as `label`, added at `where`: the state it reads is
      * reported as read by it. `field`: a command's `enabled` or `checked`,
@@ -286,18 +422,24 @@ export class Runtime {
         return undefined;
     }
     /** Evaluate one binding, holding the events whose state it read. */
-    #evaluate(evaluate, held) {
+    #evaluate(evaluate, binding) {
+        const held = binding.held;
         const reads = new Map();
+        const deps = new Map();
         const outer = this.#reads;
+        const outerDeps = this.#deps;
         const reader = this.#reader;
         this.#reads = reads;
+        this.#deps = deps;
         this.#reader = undefined;
         try {
             evaluate();
         }
         finally {
             this.#reads = outer;
+            this.#deps = outerDeps;
             this.#reader = reader;
+            binding.deps = deps;
             for (const [event, hold] of held)
                 if (!reads.has(event)) {
                     held.delete(event);
@@ -308,24 +450,82 @@ export class Runtime {
                     held.set(event, this.hold(event, why));
         }
     }
-    /** Coalesce: one evaluation pass per microtask turn, however many changes. */
+    /**
+     * A full pass: every binding is evaluated. Requested after plugin code
+     * the SDK ran, by `plugin.update()`, and on any change other than a state
+     * copy's fields. Coalesced: one pass per microtask turn, however many
+     * requests.
+     */
     invalidate() {
+        this.#full = true;
+        this.#schedule();
+    }
+    /**
+     * Fields of the SDK's copy of a state (`key`) changed: a precise pass
+     * evaluates only the bindings (and view bind functions) that read one of
+     * them, unless a full pass is due anyway.
+     */
+    changed(key, fields) {
+        let set = this.#pending.get(key);
+        if (!set)
+            this.#pending.set(key, (set = new Set()));
+        for (const field of fields)
+            set.add(field);
+        this.#schedule();
+    }
+    #schedule() {
         if (this.#scheduled)
             return;
         this.#scheduled = true;
-        queueMicrotask(() => {
-            this.#scheduled = false;
-            for (const [evaluate, held] of [...this.#bindings]) {
-                if (this.#bindings.get(evaluate) !== held)
-                    continue;
-                try {
-                    this.#evaluate(evaluate, held);
-                }
-                catch (error) {
-                    console.error(`[${this.manifest.id}] binding failed:`, error);
-                }
+        queueMicrotask(() => this.#run());
+    }
+    /**
+     * One pass. A precise pass that skips anything arms a full pass
+     * `SAFETY_PASS_MS` later (unless a full pass comes first), for plugin
+     * state changed outside code the SDK ran.
+     */
+    #run() {
+        this.#scheduled = false;
+        const full = this.#full;
+        const change = this.#pending;
+        this.#full = false;
+        this.#pending = new Map();
+        if (full) {
+            clearTimeout(this.#safety);
+            this.#safety = undefined;
+        }
+        this.#skipped = false;
+        for (const [evaluate, binding] of [...this.#bindings]) {
+            if (this.#bindings.get(evaluate) !== binding)
+                continue;
+            if (!full && !affected(binding.deps, change)) {
+                this.#skipped = true;
+                continue;
             }
-        });
+            this.#pass = full ? undefined : change;
+            try {
+                this.#evaluate(evaluate, binding);
+            }
+            catch (error) {
+                console.error(`[${this.manifest.id}] binding failed:`, error);
+            }
+            finally {
+                this.#pass = undefined;
+            }
+        }
+        if (this.#skipped && !this.#safety && !this.#stopped) {
+            this.#safety = setTimeout(() => {
+                this.#safety = undefined;
+                this.invalidate();
+            }, SAFETY_PASS_MS);
+            this.#safety.unref?.();
+        }
+    }
+    /** The plugin was disposed: cancel the pending safety pass, arm no more. */
+    stop() {
+        this.#stopped = true;
+        clearTimeout(this.#safety);
+        this.#safety = undefined;
     }
     /**
      * Host events with one `events.subscribe` per name, however many listeners.

package/dist/plugin/scope.d.ts

@@ -1,4 +1,4 @@
-import type { Runtime } from "./runtime.ts";
+import type { Change, Runtime } from "./runtime.ts";
 import type { Disposable, Plugin, PluginError, Scope } from "./types.ts";
 export declare class ScopeImpl implements Plugin {
     #private;
@@ -54,6 +54,14 @@ export declare class ScopeImpl implements Plugin {
     report(error: unknown): void;
     /** Invoke plugin code on its behalf: report failures, then refresh bindings. */
     run(handler: (...args: never[]) => unknown, ...args: unknown[]): void;
+    /**
+     * Run a listener of a state change (`player.onChange`) like `run`, except
+     * that the full pass after it is left out when it returned synchronously
+     * and read only fields of the state that `change` left alone: its result
+     * then depends on nothing new. The precise pass for the change runs
+     * anyway, and a full pass follows within `SAFETY_PASS_MS`.
+     */
+    runOn(change: Change, handler: (...args: never[]) => unknown, ...args: unknown[]): void;
     update(): void;
     dispose(): Promise<void>;
 }

package/dist/plugin/scope.js

@@ -145,6 +145,30 @@ export class ScopeImpl {
         }
         this.update();
     }
+    /**
+     * Run a listener of a state change (`player.onChange`) like `run`, except
+     * that the full pass after it is left out when it returned synchronously
+     * and read only fields of the state that `change` left alone: its result
+     * then depends on nothing new. The precise pass for the change runs
+     * anyway, and a full pass follows within `SAFETY_PASS_MS`.
+     */
+    runOn(change, handler, ...args) {
+        if (this.disposed)
+            return;
+        let full = true;
+        try {
+            const { value, deps } = this.runtime.observe(() => handler(...args));
+            if (value instanceof Promise)
+                value.catch((error) => this.report(error)).finally(() => this.update());
+            else
+                full = this.runtime.needsFull(deps, change);
+        }
+        catch (error) {
+            this.report(error);
+        }
+        if (full)
+            this.update();
+    }
     update() {
         this.runtime.invalidate();
     }

package/dist/plugin/testing.d.ts

@@ -2621,6 +2621,13 @@ export declare class TestHost implements Transport {
      * for: on a loaded machine it can finish after `settle()` returns. Poll
      * the result you assert on instead (second example).
      *
+     * `settle()` does not wait for the SDK's once-a-second full update pass
+     * (SDK 1.5.45). After `setSource` (or another player state change) only
+     * the bindings that read a changed field of `plugin.player.state` run
+     * again; state the plugin changed outside a handler without
+     * `plugin.update()` shows only in the next full pass. Have the plugin
+     * call `plugin.update()` after such a change, or wait `settle(1000)`.
+     *
      * @param ms - Extra time to wait, for debounces and timers (default 0).
      *
      * @example Wait past a debounced save

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 });
@@ -3213,6 +3256,13 @@ export class TestHost {
      * for: on a loaded machine it can finish after `settle()` returns. Poll
      * the result you assert on instead (second example).
      *
+     * `settle()` does not wait for the SDK's once-a-second full update pass
+     * (SDK 1.5.45). After `setSource` (or another player state change) only
+     * the bindings that read a changed field of `plugin.player.state` run
+     * again; state the plugin changed outside a handler without
+     * `plugin.update()` shows only in the next full pass. Have the plugin
+     * call `plugin.update()` after such a change, or wait `settle(1000)`.
+     *
      * @param ms - Extra time to wait, for debounces and timers (default 0).
      *
      * @example Wait past a debounced save
@@ -3892,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));
@@ -4253,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) => {
@@ -4316,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));
@@ -5345,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

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

package/dist/plugin/ui.d.ts

@@ -32,13 +32,23 @@ 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;
-    /** Current desired properties (bound values win over earlier `set`). */
+    /**
+     * Current desired properties (bound values win over earlier `set`). A
+     * precise pass (`Runtime.part`) skips a bind function that read none of
+     * the changed state: its last values stay.
+     */
     protected snapshot(): Record<string, PropValue>;
     protected evaluate(): void;
     /** The host already shows these values (e.g. sent as initial properties). */