@vestra-player/sdk 1.5.44 → 1.5.46

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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.
+
+- **Precise update passes.** While media plays, the player sends its state about ten times a second, and each change used to re-run every `view.bind` function and every command `enabled`, `checked`, `busy` and `reason` function of the plugin. Now the SDK records which fields of `plugin.player.state` each of them read (`position`, `paused`, `phase`, `source`, …) and, after a player state change, re-runs only those that read a field that changed: a list bound in a panel no longer re-runs on every position tick. `isCurrent` and `Media.current` count as reading the source's identity.
+- **Full passes as before** after any code of the plugin the SDK runs (a command's `run`, a window, panel or settings page callback, a listener, `onEnd`, and so on), when the promise it returned settles, after `plugin.update()`, and after every other state change (window, subtitles, panels, timeline, appearance). One exception keeps a playing list cheap: a `player.onChange` listener that returned synchronously and read only fields of the state that did not change is not followed by a full pass (a listener that read a changed field, no field at all, or returned a promise still is).
+- **A full pass at least once a second while precise passes skip something.** State a plugin changes outside code the SDK runs (its own `setInterval`, a socket callback) without calling `plugin.update()` used to show at the next player state change (within about 0.1 s while playing); now it shows at the latest about 1 s later. Call `plugin.update()` after such a change, as the documentation always said.
+- **`plugin.player.state`** reads as before (the same keys in the same order, frozen, JSON, spread, `structuredClone`, `util.inspect` and `assert.deepEqual` give the same values); its fields are getters now, so `Object.getOwnPropertyDescriptor` shows `get` instead of `value`, and `Reflect.ownKeys` and `Object.getOwnPropertySymbols` also list `Symbol(nodejs.util.inspect.custom)` (not enumerable).
+- **`Scrub.active`** turning false (a new source, a failed seek) now causes a full pass, so a binding that reads it follows.
+- **`TestHost`** runs the same code: the plugin's tests see the same passes as the player. `settle()` does not wait for the once-a-second full pass; `settle(1000)` does (`TestHost.settle`, _Test a plugin_ say so).
+
 ## 1.5.44
 
 **Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. How the SDK sends array properties changes, on players that take it (player 0.6.0); with older players it sends whole values as before. The read-only copy of the widget library gains components that need player 0.6.0 (`"minPlayerVersion": "0.6.0"` for a plugin whose Slint uses them; an older player fails to compile such a file).

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/index.js

@@ -25,6 +25,9 @@ app) {
     return {
         plugin: root,
         activated: () => runtime.activated(),
-        dispose: () => root.dispose(),
+        dispose: async () => {
+            await root.dispose();
+            runtime.stop();
+        },
     };
 }

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/player.d.ts

@@ -3,6 +3,12 @@ import { Latest } from "./runtime.ts";
 import type { Runtime } from "./runtime.ts";
 import type { ScopeImpl } from "./scope.ts";
 import type { Conditional, Disposable, Player, PlayerState, PluginError } from "./types.ts";
+/**
+ * The key of `plugin.player.state` in the runtime's field tracking
+ * (`Runtime.depends`). Its fields are the state's own, plus `stamp` for
+ * what `isCurrent` and `Media.current` compare.
+ */
+export declare const PLAYER = "player";
 export declare const rawOf: (state: PlayerState) => SourceState | undefined;
 /** A step-seek length the player accepts: 0.1–3600 seconds in tenths. */
 export declare const validStep: (seconds: unknown) => seconds is number;
@@ -14,6 +20,11 @@ export declare class PlayerService {
     readonly runtime: Runtime;
     raw: SourceState;
     state: PlayerState;
+    /**
+     * The fields the last accepted state changed (`onChange` listeners are
+     * told so a listener that read none of them needs no full pass).
+     */
+    change: ReadonlyMap<string, ReadonlySet<string>>;
     readonly output: Latest<{
         volume?: number;
         muted?: boolean;

package/dist/plugin/player.js

@@ -40,9 +40,63 @@ const audioTrack = (track) => Object.freeze({
     title: track.title,
     language: track.language,
 });
-function view(raw) {
+/**
+ * The key of `plugin.player.state` in the runtime's field tracking
+ * (`Runtime.depends`). Its fields are the state's own, plus `stamp` for
+ * what `isCurrent` and `Media.current` compare.
+ */
+export const PLAYER = "player";
+/** `util.inspect` shows a state's values, not its getters. */
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+const values = new WeakMap();
+/**
+ * The state a plugin sees: each field a getter over the same values, so the
+ * SDK learns which fields a binding or listener read (`Runtime.depends`).
+ * It behaves like the plain frozen object it was: same keys in the same
+ * order, enumerable, JSON, spread, `structuredClone` and `util.inspect`
+ * give the values.
+ */
+function tracked(runtime, data) {
+    const state = {};
+    for (const key of Object.keys(data)) {
+        const value = data[key];
+        Object.defineProperty(state, key, {
+            enumerable: true,
+            get: () => {
+                runtime?.depends(PLAYER, key);
+                return value;
+            },
+        });
+    }
+    Object.defineProperty(state, INSPECT, { value: () => data });
+    const frozen = Object.freeze(state);
+    values.set(frozen, data);
+    return frozen;
+}
+/** The fields of `next` that differ from `last` (`stamp` included). */
+function changes(last, lastRaw, next, nextRaw) {
+    const a = values.get(last);
+    const b = values.get(next);
+    const changed = [];
+    for (const key of Object.keys(b)) {
+        const x = a[key];
+        const y = b[key];
+        if (x === y)
+            continue;
+        if (x === null ||
+            y === null ||
+            typeof x !== "object" ||
+            typeof y !== "object" ||
+            JSON.stringify(x) !== JSON.stringify(y))
+            changed.push(key);
+    }
+    if (!sameStamp(lastRaw.stamp, nextRaw.stamp))
+        changed.push("stamp");
+    return changed;
+}
+function view(raw, runtime) {
     const reason = raw.terminalReason;
-    const state = Object.freeze({
+    const data = Object.freeze({
         sourceId: raw.stamp.generation,
         kind: raw.kind === "producer" ? "stream" : "media",
         phase: raw.phase,
@@ -78,6 +132,7 @@ function view(raw) {
             active: raw.audioOutput?.active ?? null,
         }),
     });
+    const state = tracked(runtime, data);
     raws.set(state, raw);
     return state;
 }
@@ -110,12 +165,18 @@ export function abortError() {
 export class PlayerService {
     runtime;
     raw = empty;
-    state = view(empty);
+    state;
+    /**
+     * The fields the last accepted state changed (`onChange` listeners are
+     * told so a listener that read none of them needs no full pass).
+     */
+    change = new Map();
     #watchers = new Set();
     #operation = 0;
     output;
     constructor(runtime) {
         this.runtime = runtime;
+        this.state = view(empty, runtime);
         // The SDK's copy of the state (a mirror): a plugin listens through
         // `watch` and the bindings that read `state`.
         runtime.on("source.state", (data) => this.accept(data), "events", true);
@@ -137,12 +198,16 @@ export class PlayerService {
             return;
         if (JSON.stringify(raw) === JSON.stringify(this.raw))
             return;
+        const last = this.state;
+        const lastRaw = this.raw;
         this.raw = raw;
-        this.state = view(raw);
+        this.state = view(raw, this.runtime);
+        const changed = changes(last, lastRaw, this.state, raw);
+        this.change = new Map([[PLAYER, new Set(changed)]]);
         for (const watcher of [...this.#watchers])
             watcher(raw);
-        // Bindings may read `player.state`; refresh them like after a handler.
-        this.runtime.invalidate();
+        // A precise pass: only the bindings that read a changed field.
+        this.runtime.changed(PLAYER, changed);
     }
     watch(watcher) {
         this.#watchers.add(watcher);
@@ -244,6 +309,7 @@ class MediaHandle {
         this.#ticket = ticket;
     }
     get current() {
+        this.#service.runtime.depends(PLAYER, "stamp");
         return this.#service.raw.stamp.generation === this.#ticket.stamp.generation;
     }
     ready(options = {}) {
@@ -313,7 +379,9 @@ class ScrubHandle {
     #pending = null;
     #watch;
     #queue;
+    #service;
     constructor(service) {
+        this.#service = service;
         this.#allowed = { ...service.raw.stamp };
         this.#watch = service.watch((raw) => {
             if (!sameStamp(raw.stamp, this.#allowed) &&
@@ -377,6 +445,9 @@ class ScrubHandle {
         this.#active = false;
         this.#queue.stop();
         void this.#watch.dispose();
+        // `active` changed, maybe outside plugin code (a new source, a failed
+        // seek): bindings that read it see it in a full pass.
+        this.#service.runtime.invalidate();
     }
 }
 const superseded = new HostError("superseded", "gesture ended");
@@ -434,10 +505,11 @@ export function player(scope) {
     return {
         get state() {
             scope.runtime.reading("source.state");
+            scope.runtime.depends(PLAYER);
             return service().state;
         },
         onChange(listener) {
-            const watch = service().watch(() => scope.run(listener, service().state));
+            const watch = service().watch(() => scope.runOn(service().change, listener, service().state));
             return scope.add({
                 dispose: async () => {
                     scope.forget(watch);
@@ -448,6 +520,7 @@ export function player(scope) {
         refresh: () => service().refresh(),
         isCurrent(state) {
             const raw = raws.get(state);
+            scope.runtime.depends(PLAYER, "stamp");
             return !!raw && sameStamp(raw.stamp, service().raw.stamp);
         },
         async open(source, options = {}) {

package/dist/plugin/runtime.d.ts

@@ -23,6 +23,20 @@ export declare const failure: (code: string, message?: string) => PluginError;
 export declare const uncertain: (error: unknown) => boolean;
 /** Mark a promise as observed so an unused `ready` never crashes the runner. */
 export declare function quiet<T>(promise: Promise<T>): Promise<T>;
+/**
+ * The fields of the SDK's state copies that a binding or listener read, by
+ * state (`player`: `plugin.player.state`). An empty set: the state was
+ * taken whole (no field read was seen), so any change of it counts.
+ */
+export type Deps = Map<string, Set<string>>;
+/** A change of the SDK's state copies: the fields that changed, by state. */
+export type Change = ReadonlyMap<string, ReadonlySet<string>>;
+/**
+ * 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 declare const SAFETY_PASS_MS = 1000;
 export declare const same: (a: Json | undefined, b: Json | undefined) => boolean;
 /** One value in flight, only the newest waiting. Each push learns its fate. */
 export declare class Latest<T> {
@@ -76,6 +90,36 @@ export declare class Runtime {
      * on it, so the event counts as listened to while the binding reads it.
      */
     reading(event: string): void;
+    /**
+     * 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: string, field?: string): void;
+    /**
+     * 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<T>(token: object, read: () => T): {
+        value: T;
+    } | undefined;
+    /**
+     * Run plugin code (a state listener) and return the state copy fields it
+     * read; they are not counted as a binding's.
+     */
+    observe<T>(run: () => T): {
+        value: T;
+        deps: Deps;
+    };
+    /**
+     * 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: Deps, change: Change): boolean;
     /**
      * Evaluate `read` as `label`, added at `where`: the state it reads is
      * reported as read by it. `field`: a command's `enabled` or `checked`,
@@ -88,8 +132,21 @@ export declare class Runtime {
      * line (`main.ts:353`). Captured now, formatted when asked.
      */
     callSite(): () => string | undefined;
-    /** 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(): void;
+    /**
+     * 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: string, fields: Iterable<string>): void;
+    /** The plugin was disposed: cancel the pending safety pass, arm no more. */
+    stop(): void;
     /**
      * Host events with one `events.subscribe` per name, however many listeners.
      * Without the `events` capability the listener simply never fires.