@vestra-player/sdk 1.5.44 → 1.5.45

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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).

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

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

@@ -3213,6 +3213,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

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" });
  * ```
  *
@@ -1706,8 +1709,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 +1847,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 +1872,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 +5706,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

@@ -38,7 +38,11 @@ export declare abstract class ViewBase implements View {
     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). */

package/dist/plugin/ui.js

@@ -247,18 +247,32 @@ export class ViewBase {
         this.flush();
     }
     bind(props) {
-        this.#binders.set(props, this.scope.runtime.callSite());
+        // `token` names this binding of this view in the runtime's read
+        // tracking: the same function bound to two views is two parts.
+        this.#binders.set(props, {
+            site: this.scope.runtime.callSite(),
+            token: {},
+        });
         this.scope.update();
         return this.scope.onDispose(() => {
             this.#binders.delete(props);
         });
     }
-    /** 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.
+     */
     snapshot() {
-        for (const [binder, site] of this.#binders) {
+        const runtime = this.scope.runtime;
+        for (const [binder, { site, token }] of this.#binders) {
             try {
-                const props = this.scope.runtime.reader("a view's bind", site, binder);
-                for (const [key, value] of Object.entries(encode(props)))
+                // Encoded inside the part: what encoding reads counts as the
+                // function's (a state object it returned).
+                const result = runtime.part(token, () => encode(runtime.reader("a view's bind", site, binder)));
+                if (!result)
+                    continue;
+                for (const [key, value] of Object.entries(result.value))
                     this.#values.set(key, value);
             }
             catch (error) {

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.44: full reference
+# @vestra-player/sdk 1.5.45: 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.
 
@@ -1903,6 +1903,8 @@ host.handle("processing.replace", () => {
 
 `await host.settle()` after every action that makes the plugin talk to the player; `host.settle(400)` also lets debounces and timers due by then fire. Then assert on what the host recorded: `host.window(id).props` (kebab-case names), `host.command(id).state`, `host.osd`, `host.source`.
 
+`settle` does not wait for the once-a-second full update pass (SDK 1.5.45): after `host.setSource(...)` only the bindings that read a changed field of `plugin.player.state` run again. A value your plugin changed outside a handler (a timer, a promise continuation, a child process) without `plugin.update()` shows in the next full pass, at most about a second later; call `plugin.update()` in the plugin after such a change, or wait `await host.settle(1000)` in the test.
+
 `settle` waits only for calls to the player. Work the plugin does on its own (reading or parsing a file, a child process, a network request) can finish later on a loaded machine; poll the value you assert on instead:
 
 ```ts nocheck
@@ -3866,14 +3868,18 @@ There is no cleanup function to return from `activate`. Because every resource i
 A plugin's state is plain variables. The SDK keeps the player in step with it through **bindings** and the **update pass**:
 
 - A binding is a function the SDK calls to get a current value: view.bind(() => props) for a window, panel or settings page, and the function form of a command's `enabled`, `checked`, `busy` and `reason` (Bindable).
-- In an update pass the SDK calls every binding of the plugin, compares each result with the value it last sent, and sends only what changed.
+- In an update pass the SDK calls the bindings of the plugin, compares each result with the value it last sent, and sends only what changed.
 
-Update passes run:
+A **full pass** calls every binding. It runs:
 
 - after every handler the SDK calls returns (a command's `run`, a view callback, an `onChange`, `onStatus`, `onEnd` or `onStop` listener), and again when the promise it returned settles;
-- after the player, subtitle, panel position, filter or export state changes;
+- after the subtitle, window, panel position, timeline, appearance, filter or export state changes;
 - when the plugin calls plugin.update().
 
+A **precise pass** follows a change of the player state (SDK 1.5.45). While media plays the player sends its state about ten times a second, mostly with only `position` changed. The SDK notes which fields of `plugin.player.state` each binding read the last time it ran (each `view.bind` function on its own; a command's four functions together) and calls only the bindings that read a field that changed. A panel whose list reads nothing of the player state is not rebuilt on every position tick; a label that shows the position is. `player.isCurrent` and `Media.current` count as reading the source. A `player.onChange` listener is followed by a full pass, as above, unless it returned synchronously and read only fields that did not change.
+
+A precise pass cannot see state the plugin changed by itself. So while precise passes leave bindings out, a full pass follows at least once a second: a variable your own timer changed without `plugin.update()` appears within about a second (before SDK 1.5.45 it usually appeared at the next position tick). Call `plugin.update()` after such a change to show it at once.
+
 Several requests within one microtask are merged into one pass, and every target has at most one write in flight: values that change meanwhile are merged into the next write. A binding that changes 60 times a second therefore costs one write per round trip, never a growing queue.
 
 One click, end to end (a bookmark window; the video is at 42 s):
@@ -3893,7 +3899,7 @@ sequenceDiagram
     S->>U: the label changes, Jump to bookmark is enabled
 ```
 
-The rule that follows: **state you change outside a handler, or after an `await` inside one, appears only at the next pass.** Changing a variable from your own `setInterval`, a socket callback or the middle of a long task shows nothing until something triggers a pass; call `plugin.update()` after such a change. Keep a slider responsive while dragging shows the pattern; How Slint and TypeScript talk explains `set` versus `bind` for views.
+The rule that follows: **state you change outside a handler, or after an `await` inside one, appears only at the next full pass.** Changing a variable from your own `setInterval`, a socket callback or the middle of a long task shows nothing until something triggers one (at most about a second while media plays); call `plugin.update()` after such a change. Keep a slider responsive while dragging shows the pattern; How Slint and TypeScript talk explains `set` versus `bind` for views.
 
 #### Stopping
 
@@ -4009,7 +4015,7 @@ const toggle = plugin.commands.add({
 
 - **The id is the command's identity.** It is unique within the plugin; the player knows the command as `<manifest id>/<id>`. The user's own key bindings are stored under that pair, so changing a title or moving the command to another menu keeps them.
 - **`path` puts it in the main menu.** Leave it out for a command that only has bindings or lives in a panel's context menu (Panel.showMenu); it then needs a `title`.
-- **State is declared, not pushed.** `enabled`, `checked`, `busy` and `reason` are values or functions (Bindable); `enabled` and `checked` may also be conditions from `plugin.when` (below). Functions are evaluated in every update pass and sent only when they change, so the menu's check mark follows the player without a listener you write. Command.set replaces them later.
+- **State is declared, not pushed.** `enabled`, `checked`, `busy` and `reason` are values or functions (Bindable); `enabled` and `checked` may also be conditions from `plugin.when` (below). Functions are evaluated in every full update pass, and after a player state change only if they read a field that changed; they are sent only when they change, so the menu's check mark follows the player without a listener you write. Command.set replaces them later.
 - **The player calls `run` only when it can run.** While a command is disabled or busy, neither its menu item nor its binding calls `run`; `reason` tells the user why (it appears in the menu and, for a key press, on the video).
 - **Titles and paths are fixed.** They cannot change in place. A menu that follows changing content (tracks, presets, a radio group) lives in a child scope that is disposed and rebuilt when the content changes; `order` keeps its place (Handles and scopes).
 - Disposing the command removes it from the menu and the binding table; the same id can be added again at once. The number of commands per plugin and per player is limited (Reference: limits); the limit stops runaway menus, so cap menus built from media content (tracks, chapters) yourself.
@@ -4266,7 +4272,7 @@ player.openStream (capability `producer.av`) makes a source whose picture and so
 
 #### Next and previous
 
-The player's **Previous** and **Next** (menu, keys, the bottom bar) are not tied to a playlist. One plugin at a time can **provide the sequence** with provideSequence, giving `next()`, `previous()` and two flags, `canNext` and `canPrevious`, which are bindings re-evaluated in every update pass.
+The player's **Previous** and **Next** (menu, keys, the bottom bar) are not tied to a playlist. One plugin at a time can **provide the sequence** with provideSequence, giving `next()`, `previous()` and two flags, `canNext` and `canPrevious`, which are bindings re-evaluated in every full update pass, and after a player state change only if they read a changed field.
 
 - Every plugin sees the flags as `player.state.can.next` and `can.previous`, and player.next() asks the provider to move; the provider's `next` runs in its own scope.
 - A second provider fails with `conflict` and does not fail activation; it is tried again when its flags change, so it takes over once the first provider goes away.
@@ -4627,12 +4633,12 @@ export component ListPanel inherits Rectangle {
 
 |                  | `set({ x })`                                                                            | `bind(() => ({ x }))`                                                                 |
 | ---------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| When it is sent  | Immediately (in the next write).                                                        | In every update pass, if `x` differs from the last value sent.                        |
+| When it is sent  | Immediately (in the next write).                                                        | In every full update pass, and after a player state change if the function read a changed field; when `x` differs from the last value sent. |
 | Same value again | Sent again. Use this to pull a control back to the model value after the user moved it. | Not sent. A field the user edited stays as the user left it until your value changes. |
 | Write fails      | Retried with back-off (0.25 s doubling up to 30 s).                                     | Not repeated until the value changes.                                                 |
 | Typical use      | One-off values: a document, a reset.                                                    | Everything derived from plugin state: labels, enabled flags, lists, status lines.     |
 
-Update passes run after every handler the SDK calls, after player and other state changes, and when you call plugin.update(); several requests are merged into one pass, and each view has at most one write in flight (The update pass has the details).
+Update passes run after every handler the SDK calls, after player and other state changes, and when you call plugin.update(); several requests are merged into one pass, and each view has at most one write in flight. After a player state change only the bind functions that read a changed field of `plugin.player.state` run again (The update pass has the details).
 
 The rule to remember: **state you change after an `await` inside a handler appears only when the handler finishes**, unless something else triggers a pass. Call `plugin.update()` right after changing it (see Keep a slider responsive while dragging).
 
@@ -5810,6 +5816,7 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [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. | — |
 | [1.5.42](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1542) | **Nobody.** Documentation only: no API changes, `apiVersion` stays `vestra/1`, no player version needed. | — |
@@ -6367,8 +6374,10 @@ interface CommandState {
 
 ### Bindable
 
-A value, or a function the SDK re-evaluates on every update pass (see
-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 Scope.update); only
+changes are sent to the player.
 
 ```ts
 type Bindable<T> = T | (() => T);
@@ -6377,9 +6386,9 @@ type Bindable<T> = T | (() => T);
 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",
@@ -6800,8 +6809,9 @@ from the menu and the binding table; the id can be added again right away.
 
 The handle of one menu item and its keys. Its state (`enabled`, `checked`,
 `busy`, `reason`) is bound: functions given to Commands.add or
-Command.set are evaluated again in every update pass and only
-changes reach the player. Its title, path, bindings and button cannot
+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 Scope) and add it
 again. Disposing it, its scope or stopping the plugin removes the menu
 item, its keys and its bar button.
@@ -6864,7 +6874,7 @@ const exportCommand = plugin.commands.add({
   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" });
 ```
 
@@ -7415,8 +7425,9 @@ a property back: a value the user changes reaches it only through a
 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
-Scope.update) and sends only what changed, at most one write in
+full update pass (after each handler it calls, on 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
@@ -7519,7 +7530,11 @@ interface View {
    * Keep properties equal to a function of the plugin's state.
    *
    * 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 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.
    *
@@ -7537,8 +7552,9 @@ 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(() => ({
@@ -10947,8 +10963,8 @@ 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
    * const playAt = async (at: number) => {
@@ -17001,6 +17017,13 @@ class TestHost implements Transport {
    * or parsing a file, a child process, a network request) is not waited
    * 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).
    * @capability None.
    * @throws Never.

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.44: 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.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.
 
 **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: L2216–2289.
+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.
 
 **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: L2290–2350.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2292–2352.
 
-**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–2019; TestHost: L15463.
+**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.
 
 **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 L5945.
+- Others: PluginError, llms-full.txt L5952.
 
 ## 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–2019; Publish a plugin L2020–2121; Troubleshooting L2122–2215
-- Reference: Manifest L2216–2289; Capabilities L2290–2350; Limits L2351–2496; Commands, menus and bindings L2497–3022; Platforms L3023–3053; Theme L3054–3403; Command line L3404–3461; Error codes L3462–3509; Translations L3510–3602; Test host L3603–3789
-- Explanation: How a plugin runs L3790–3988; Commands, menus and key bindings L3989–4143; Playback state, controls and sources L4144–4303; Video and audio processing L4304–4424; Windows, panels, settings pages, dialogs and the OSD L4425–4687; GPU and software rendering L4688–4704; The player's Rust core L4705–5046; How the player runs and talks to plugins L5047–5386
-- Guidelines: Plugin rules L5387–5398; Interface guidelines L5399–5515; Menu guidelines L5516–5574
-- Upgrading: Migrate a plugin to English source text L5575–5724; Migrating off package rollback (1.5.16, removed in 1.5.17) L5725–5802; Who must change, release by release L5803–5867
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5868–15136
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15137–18004
+- 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
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L6284, Scope L6020, PluginError L5945, Disposable L5883
-- Commands L6871; When L6469; Windows L7808; Panels L9254; Dialogs L9924; Player L10665; video: VideoFilter L11545, VideoView L11645, RenderOptions L11732, VideoShaders L11810, VideoUpscaling L12168; audio: AudioFilter L11590; Subtitles L12404; media: MediaCapture L12808; Resolvers L13038; Packages L13440; Osd L11410; Host L11252; Clipboard L13769; Power L13856; Tools L13915; Storage L14067; System L14266; Secrets L14346; window: MainWindow L9571; App L9751; Rendering L14609; Bindings L13668; Ui L7160; Timeline L9483; Drops L8501; Appearance L8582; I18n L8815; Settings L9098.
+- 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.
 
 ## 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. L18439–18534
-- blur: A tool window with one slider that blurs the playing video. L18535–18802
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18803–19141
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19142–19334
-- panel-menu: A sidebar panel with its own right-click menu. L19335–19549
-- menus: Radio menu items, separator groups and a menu item whose title changes. L19550–19715
-- theme-widgets: A tool window drawn with the player's theme and widgets. L19716–19885
-- markdown: A window that shows a Markdown document. L19886–20088
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L20089–20262
+- 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
 
 ## Optional
 

package/package.json

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