@vestra-player/sdk 1.5.43 → 1.5.45

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> {
@@ -54,6 +68,12 @@ export declare class Runtime {
     readonly app: App;
     /** `plugin.i18n.locale`, from the start-up handshake; English when unknown. */
     readonly locale: Locale;
+    /**
+     * Protocol additions the player advertises at start-up (`features` in the
+     * handshake's app data, player 0.6.0): `ui.patch` (row patches of
+     * property writes). Not part of the plugin API; empty for older players.
+     */
+    readonly features: ReadonlySet<string>;
     constructor(transport: Transport, manifest: PluginManifest, directory: string, dataDirectory?: string, app?: unknown);
     can(capability: string): boolean;
     /** Lazily created singletons shared by every scope of this plugin. */
@@ -70,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`,
@@ -82,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();
@@ -132,6 +181,12 @@ export class Runtime {
     app;
     /** `plugin.i18n.locale`, from the start-up handshake; English when unknown. */
     locale;
+    /**
+     * Protocol additions the player advertises at start-up (`features` in the
+     * handshake's app data, player 0.6.0): `ui.patch` (row patches of
+     * property writes). Not part of the plugin API; empty for older players.
+     */
+    features;
     constructor(transport, manifest, directory, dataDirectory, app) {
         this.#transport = transport;
         this.dataDirectory = dataDirectory;
@@ -139,6 +194,11 @@ export class Runtime {
         this.host = createWire(transport);
         const host = this.host;
         this.app = appInfo(app, () => host.app.system());
+        const features = app
+            ?.features;
+        this.features = new Set(Array.isArray(features)
+            ? features.filter((name) => typeof name === "string")
+            : []);
         this.locale = LOCALES.includes(transport.locale ?? "")
             ? transport.locale
             : "en";
@@ -185,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())
@@ -220,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`,
@@ -275,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);
@@ -297,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/settings.js

@@ -61,8 +61,8 @@ class Page extends ViewBase {
     live() {
         return this.#registered && !this.closed;
     }
-    write(property, value) {
-        return this.scope.runtime.host.settings.set(this.#id, property, value);
+    write(property, write) {
+        return this.scope.runtime.host.settings.set(this.#id, property, write);
     }
     async dispose() {
         if (this.closed)

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