@vestra-player/sdk 1.5.43 → 1.5.45

package/CHANGELOG.md

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

package/dist/player-runtime.d.ts

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

package/dist/player-runtime.js

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

package/dist/plugin/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

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

package/dist/plugin/patch.js

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

package/dist/plugin/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 = {}) {