@vestra-player/sdk 1.6.17 → 1.6.19

package/dist/plugin/errors.js

@@ -0,0 +1,35 @@
+/**
+ * Error helpers shared by every part of the SDK (L1, refactor plan §2.2):
+ * no state, no update passes. They lived in `runtime.ts` (`abortError` in
+ * `player.ts`), so a module that needed one imported the pass scheduler
+ * with it, and `stream.ts` and `player.ts` imported each other.
+ */
+import { HostError } from "../wire.js";
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function toError(error) {
+    if (error instanceof Error) {
+        const coded = error;
+        if (typeof coded.code !== "string")
+            Object.defineProperty(coded, "code", {
+                value: error.name === "AbortError" ? "aborted" : "error",
+                enumerable: false,
+                writable: true,
+            });
+        return coded;
+    }
+    return new HostError("error", String(error));
+}
+export const failure = (code, message = code) => new HostError(code, message);
+/** Host replies are definite; anything else (lost reply, client timeout) is not. */
+export const uncertain = (error) => !(error instanceof HostError) || error.code === "timeout";
+/** Mark a promise as observed so an unused `ready` never crashes the runner. */
+export function quiet(promise) {
+    promise.catch(() => { });
+    return promise;
+}
+export function abortError() {
+    const error = new Error("aborted");
+    error.name = "AbortError";
+    error.code = "aborted";
+    return error;
+}

package/dist/plugin/filters.js

@@ -1,4 +1,4 @@
-import { failure, sleep, uncertain } from "./runtime.js";
+import { failure, sleep, uncertain } from "./errors.js";
 import { playerOf } from "./player.js";
 const nothing = JSON.stringify({ nodes: [], offsetMs: 0 });
 class FilterHandle {

package/dist/plugin/index.d.ts

@@ -6,7 +6,7 @@
  * @internal
  */
 import type { Transport } from "../wire.ts";
-import type { PluginManifest, RuntimeOptions } from "./runtime.ts";
+import type { PluginManifest, RuntimeOptions } from "./connection.ts";
 import type { Plugin } from "./types.ts";
 export type * from "./types.ts";
 export type { PluginManifest, RuntimeOptions };

package/dist/plugin/index.js

@@ -1,4 +1,6 @@
-import { failure, Runtime, stopReason } from "./runtime.js";
+import { Runtime } from "./runtime.js";
+import { stopReason } from "./connection.js";
+import { failure } from "./errors.js";
 import { ScopeImpl } from "./scope.js";
 import { playerOf } from "./player.js";
 import { windowOf } from "./window.js";

package/dist/plugin/language.js

@@ -1,6 +1,6 @@
 /** `plugin.i18n`: the interface language of this run and text values (read-only). */
 import { Catalog, isTextValue, LIST_STYLES, loadPackageCatalog, renderText, textKey, textProblem, } from "../i18n.js";
-import { failure } from "./runtime.js";
+import { failure } from "./errors.js";
 /** Copy arguments (arrays and objects only; texts are already frozen). */
 const copyArgs = (args) => Array.isArray(args) ? Object.freeze([...args]) : Object.freeze({ ...args });
 /** `plugin.i18n.text`: a plain, frozen text value (no translation here). */

package/dist/plugin/latest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The single-flight write queue (L1, refactor plan §2.2): a view's
+ * property writes, a command's state, an OSD panel. It knows nothing of
+ * update passes (it lived in `runtime.ts`, beside the pass scheduler).
+ */
+/** One value in flight, only the newest waiting. Each push learns its fate. */
+export declare class Latest<T> {
+    #private;
+    constructor(send: (value: T) => Promise<void>);
+    push(value: T): Promise<boolean>;
+    stop(): void;
+}

package/dist/plugin/latest.js

@@ -0,0 +1,52 @@
+/**
+ * The single-flight write queue (L1, refactor plan §2.2): a view's
+ * property writes, a command's state, an OSD panel. It knows nothing of
+ * update passes (it lived in `runtime.ts`, beside the pass scheduler).
+ */
+/** One value in flight, only the newest waiting. Each push learns its fate. */
+export class Latest {
+    #queued = [];
+    #running = false;
+    #stopped = false;
+    #send;
+    constructor(send) {
+        this.#send = send;
+    }
+    push(value) {
+        if (this.#stopped)
+            return Promise.resolve(false);
+        return new Promise((resolve, reject) => {
+            for (const older of this.#queued.splice(0))
+                older.settle(false);
+            this.#queued.push({
+                value,
+                settle: (ok, error) => error === undefined ? resolve(ok) : reject(error),
+            });
+            if (!this.#running)
+                void this.#drain();
+        });
+    }
+    stop() {
+        this.#stopped = true;
+        for (const older of this.#queued.splice(0))
+            older.settle(false);
+    }
+    async #drain() {
+        this.#running = true;
+        try {
+            let next;
+            while ((next = this.#queued.shift()) && !this.#stopped) {
+                try {
+                    await this.#send(next.value);
+                    next.settle(true);
+                }
+                catch (error) {
+                    next.settle(false, error);
+                }
+            }
+        }
+        finally {
+            this.#running = false;
+        }
+    }
+}

package/dist/plugin/local.js

@@ -9,8 +9,7 @@
 import { spawn } from "node:child_process";
 import { access, constants, stat } from "node:fs/promises";
 import { delimiter, isAbsolute, join } from "node:path";
-import { failure } from "./runtime.js";
-import { abortError } from "./player.js";
+import { abortError, failure } from "./errors.js";
 /** SIGTERM first, SIGKILL if the process is still there after this long. */
 const KILL_AFTER_MS = 300;
 const lastLine = (text) => text

package/dist/plugin/markdown.d.ts

@@ -1,5 +1,5 @@
 import type { Json } from "../wire.ts";
-import type { Runtime } from "./runtime.ts";
+import type { Connection } from "./connection.ts";
 import type { ScopeImpl } from "./scope.ts";
 import type { MarkdownOptions, MarkdownRef } from "./types.ts";
 export declare const MARKDOWN_LIMITS: Readonly<{
@@ -43,5 +43,5 @@ export declare function httpsDownload(url: string, options: {
  * `<dataDirectory>/.vestra-cache/images/` (the Markdown limits: 4 MB, 10 s,
  * 4 at a time per plugin, 32 MB of cache, a day). Rejects `unavailable`.
  */
-export declare function remoteImageFile(runtime: Runtime, url: string): Promise<string>;
+export declare function remoteImageFile(runtime: Connection, url: string): Promise<string>;
 export declare function markdown(scope: ScopeImpl, text: string, options?: MarkdownOptions): Promise<MarkdownRef>;

package/dist/plugin/markdown.js

@@ -7,7 +7,7 @@
 import { createHash } from "node:crypto";
 import { mkdir, readdir, rename, stat, unlink, utimes, writeFile, } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import { failure } from "./runtime.js";
+import { failure } from "./errors.js";
 export const MARKDOWN_LIMITS = Object.freeze({
     /** Text bytes (UTF-8). */
     textBytes: 256 * 1024,

package/dist/plugin/media.js

@@ -1,4 +1,4 @@
-import { failure, sleep, uncertain } from "./runtime.js";
+import { failure, sleep, uncertain } from "./errors.js";
 import { playerOf } from "./player.js";
 const TERMINAL = ["completed", "failed", "cancelled"];
 /** The player's sets for each {@link ExportEncoding} field. */

package/dist/plugin/osd.js

@@ -1,6 +1,6 @@
 /** On-screen display: a transient line and a persistent information block. */
-import { Latest } from "./runtime.js";
-import { failure } from "./runtime.js";
+import { Latest } from "./latest.js";
+import { failure } from "./errors.js";
 import { isTextValue, textProblem } from "../i18n.js";
 /**
  * The player's limits on the on-screen display ({@link Osd}), counted on

package/dist/plugin/packages.js

@@ -1,7 +1,7 @@
 /** Package validation, install and uninstall (`plugins.manage`). */
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
-import { failure, sleep, uncertain } from "./runtime.js";
+import { failure, sleep, uncertain } from "./errors.js";
 const TERMINAL = [
     "committed",
     "cancelled",

package/dist/plugin/passes.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The update passes (L2, refactor plan §2.2): bindings, the state copy
+ * fields they read (`reading`, `depends`, `part`, `observe`, `reader`),
+ * full and precise passes (`invalidate`, `changed`) and the safety pass.
+ * It uses the connection (`hold`) and nothing it builds on imports it
+ * (`scripts/check-layers.mjs`).
+ */
+import type { Connection } from "./connection.ts";
+import type { Disposable } from "./types.ts";
+/**
+ * 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;
+/**
+ * Read-only counters of the update passes, for the SDK's own
+ * characterisation tests and benchmark (`test/golden-traces.test.ts`,
+ * `scripts/bench.mjs`): how many passes ran, how many were full, how many
+ * bindings and view bind functions (parts) were evaluated or skipped. Not
+ * part of the plugin API; counting changes no behaviour.
+ */
+export interface PassCounts {
+    /** Passes run (`Passes.#run`), precise and full. */
+    passes: number;
+    /** Of them, full passes (every binding evaluated). */
+    fullPasses: number;
+    /** Bindings evaluated (`Passes.#evaluate`). */
+    evaluations: number;
+    /** View bind functions evaluated inside a binding (`Passes.part`). */
+    parts: number;
+    /** View bind functions a precise pass skipped (`Passes.part`). */
+    skippedParts: number;
+    /**
+     * Full passes the safety timer requested (`SAFETY_PASS_MS` after a
+     * precise pass skipped something), counted when the timer fires.
+     */
+    safetyPasses: number;
+}
+/** The update pass scheduler of one plugin (`Runtime` delegates to it). */
+export declare class Passes {
+    #private;
+    /** Pass counters, read by the SDK's own tests and benchmark ({@link PassCounts}). */
+    readonly counts: PassCounts;
+    constructor(connection: Connection);
+    bind(evaluate: () => void): Disposable;
+    /**
+     * A service's state for `event` is read: a binding evaluated now depends
+     * 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`,
+     * which a `plugin.when` condition can replace.
+     */
+    reader<T>(label: string, where: (() => string | undefined) | undefined, read: () => T, field?: boolean): T;
+    /**
+     * 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;
+}

package/dist/plugin/passes.js

@@ -0,0 +1,341 @@
+/**
+ * The state each event keeps current, and whether `plugin.when` can say
+ * the same without the plugin running.
+ */
+const STATE = {
+    "source.state": { name: "plugin.player.state", when: true },
+    "window.state": { name: "plugin.window.state", when: true },
+    "appearance.changed": { name: "plugin.appearance", when: true },
+    "timeline.changed": { name: "plugin.timeline.marks", when: false },
+    "commands.keys": { name: "plugin.commands.keys", when: false },
+    "playback.backend": { name: "plugin.subtitles.state", when: false },
+    "resolvers.fileTypes": {
+        name: "plugin.resolvers.fileTypes",
+        when: false,
+    },
+};
+/** 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;
+/** The update pass scheduler of one plugin (`Runtime` delegates to it). */
+export class Passes {
+    /** The plugin's connection: holds the events a binding reads. */
+    #connection;
+    /** Each binding with the events whose state it read last time (held). */
+    #bindings = new Map();
+    /** The events read by the binding being evaluated, with who read them. */
+    #reads;
+    /** 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;
+    /** Pass counters, read by the SDK's own tests and benchmark ({@link PassCounts}). */
+    counts = {
+        passes: 0,
+        fullPasses: 0,
+        evaluations: 0,
+        parts: 0,
+        skippedParts: 0,
+        safetyPasses: 0,
+    };
+    constructor(connection) {
+        this.#connection = connection;
+    }
+    bind(evaluate) {
+        const held = new Map();
+        const binding = { held, deps: new Map() };
+        this.#bindings.set(evaluate, binding);
+        this.invalidate();
+        return {
+            dispose: async () => {
+                if (this.#bindings.get(evaluate) !== binding)
+                    return;
+                this.#bindings.delete(evaluate);
+                for (const hold of held.values())
+                    await hold.dispose();
+                held.clear();
+            },
+        };
+    }
+    /**
+     * A service's state for `event` is read: a binding evaluated now depends
+     * on it, so the event counts as listened to while the binding reads it.
+     */
+    reading(event) {
+        const reads = this.#reads;
+        if (!reads || reads.has(event))
+            return;
+        const reader = this.#reader;
+        const state = STATE[event];
+        reads.set(event, () => {
+            const read = state?.name ?? event;
+            const site = reader?.where?.();
+            const at = site ? ` (${site})` : "";
+            if (!reader)
+                return `a binding reads ${read}`;
+            if (!reader.field)
+                return `${reader.label} reads ${read}${at}`;
+            const hint = state?.when ? " — use plugin.when" : "";
+            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;
+            this.counts.skippedParts++;
+            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;
+        }
+        this.counts.parts++;
+        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`,
+     * which a `plugin.when` condition can replace.
+     */
+    reader(label, where, read, field = false) {
+        const outer = this.#reader;
+        this.#reader = { label, where, field };
+        try {
+            return read();
+        }
+        finally {
+            this.#reader = outer;
+        }
+    }
+    /** Evaluate one binding, holding the events whose state it read. */
+    #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;
+        this.counts.evaluations++;
+        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);
+                    void hold.dispose();
+                }
+            for (const [event, why] of reads)
+                if (!held.has(event))
+                    held.set(event, this.#connection.hold(event, why));
+        }
+    }
+    /**
+     * 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.#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();
+        this.counts.passes++;
+        if (full)
+            this.counts.fullPasses++;
+        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.#connection.manifest.id}] binding failed:`, error);
+            }
+            finally {
+                this.#pass = undefined;
+            }
+        }
+        if (this.#skipped && !this.#safety && !this.#stopped) {
+            this.#safety = setTimeout(() => {
+                this.#safety = undefined;
+                this.counts.safetyPasses++;
+                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;
+    }
+}

package/dist/plugin/player.d.ts

@@ -1,8 +1,8 @@
 import type { SourceIntent, SourceStamp, SourceState, SourceTicket } from "../source.ts";
-import { Latest } from "./runtime.ts";
+import { Latest } from "./latest.ts";
 import type { Runtime } from "./runtime.ts";
 import type { ScopeImpl } from "./scope.ts";
-import type { Conditional, Disposable, Player, PlayerState, PluginError } from "./types.ts";
+import type { Conditional, Disposable, Player, PlayerState } 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
@@ -13,7 +13,6 @@ 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;
 export declare const sameStamp: (a: SourceStamp, b: SourceStamp) => boolean;
-export declare function abortError(): PluginError;
 /** One per plugin: the state store and the operation book client. */
 export declare class PlayerService {
     #private;