@vestra-player/sdk 1.6.17 → 1.6.19

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.6.19
+
+**Who must change: nobody.** Step 1 of the SDK refactor, batches B and C (`doc/specs/sdk-refactor.md` §4 in the player repository): `src/plugin/runtime.ts` and `src/plugin/ui.ts` are split by layer; no API, behaviour or wire change, `apiVersion` stays `vestra/1`.
+
+- **`runtime.ts` is split into four modules.** `connection.ts` (L1) owns the transport and its typed client, the event subscriptions with their `why`/`mirror` marks (`on`, `hold`, `raw`), the call site of a listener, the activation state (`starting`, `declaring`, `activated`) and the handshake facts (`app`, `locale`, `features`); `passes.ts` (L2) holds the update passes (`bind`, `reading`, `depends`, `part`, `observe`, `needsFull`, `reader`, `invalidate`, `changed`, the safety pass) and the pass counters; `errors.ts` holds `failure`, `quiet`, `uncertain`, `toError`, `sleep` and `abortError` (from `player.ts`); `latest.ts` holds the `Latest` single-flight queue. `Runtime` stays, as the connection plus the pass methods delegated to its `Passes`, so `runtime.host`, `runtime.on`, `runtime.bind` and the rest are unchanged for every caller, `TestHost` and the player's runner.
+- **No module imports the pass scheduler for a helper any more**: the SDK's modules take the helpers from `errors.ts` and `latest.ts`, and `player.ts` and `stream.ts` no longer import each other.
+- **A layer check in `npm run check`** (`scripts/check-layers.mjs`): the wire and its clients (L0) and the primitives (L1: `connection`, `errors`, `latest`, `values`, `stream`, `services`, `local`, `osd`, `bindings`, `language`, `packages`, `markdown`, `drops`) must not import `passes.ts` or `runtime.ts`, nor load `passes.ts` through other modules, value imports under `src/` must not form a cycle (beyond one known cycle among the test host's modules), and a relative import the check cannot resolve fails. Three L1 → L2 edges that wait for the `player.ts` split are printed as a note on every run.
+- **`ui.ts` is split into `src/plugin/view/` and a dialogs service** (batch C). `view/writer.ts` (L1) is the write path of one view: values, encoding and comparison with what was sent, row patches, parts of large writes (`more`), the value limits, `stale` fallback and the back-off after a failed write; it knows nothing of passes. `view/binder.ts` (L2) holds `bind`, `snapshot` and `evaluate` with the read tracking of the passes. `view/base.ts` keeps `ViewBase` for windows, panels and settings pages: callbacks plus a writer and a binder over it, and, as before, every view joins the update passes when made. `view/window.ts` (tool windows), `view/panel.ts` (panels), `view/layout.ts` (the panel positions, `LayoutService`) and `view/image.ts` (`plugin.ui` and image values) hold the rest; `plugin.dialogs` moved to `services/dialogs.ts`. Commands take `ImageHandle` from `view/image.ts`, so the command module no longer imports the view module. Every write, its order and its back-off are the code as it was, moved.
+- **The layer check covers the views**: `view/writer.ts`, `view/image.ts` and `services/dialogs.ts` are L1 and must not import the framework, which now includes `view/binder.ts`.
+- Golden wire traces, host scenarios, pass counts and the API surface snapshot are identical; the public declarations (`dist/index.d.ts`, `dist/plugin/types.d.ts`, `dist/plugin/testing/index.d.ts`, `dist/player-runtime.d.ts`) are unchanged.
+
+## 1.6.18
+
+**Who must change: nobody.** Characterisation tests for the SDK refactor (step 0 of the plan, `doc/specs/sdk-refactor.md` §4.0 in the player repository); no API change, no wire change, `apiVersion` stays `vestra/1`.
+
+- **Golden wire traces** (`test/golden-traces.test.ts`): the ten examples, and the six built-ins named by the plan when `VESTRA_PLAYER` points at a player checkout, run one fixed script against `TestHost` (start, open a source, three state changes, one command, dispose); the `(method, params)` sequence, every `events.subscribe` line with its `mirror`/`why` marks (line numbers stripped) and the update-pass counts per phase are compared with `test/fixtures/traces/*.json`. Eight host scenarios (`host-*.json`) pin the test host's own edges: `disconnect()` with requests in flight, the `commands.keys` push after `commands.register` against `settle()`, `press`, `handle()`/`reset()`, a stream producer's temporary files, `startPlugin` with a `taken` conflict, the `VESTRA_PLUGIN_RESIDENCY=1` line and a host never started. `UPDATE_TRACES=1` rewrites them.
+- **API surface snapshot** (`scripts/api-surface.mjs`, `npm run api-surface -- --check|--update`, `test/api-surface.test.ts`): every exported declaration and member of the `.` and `./testing` entries (the declaration files package.json `exports` names), sorted, in `test/fixtures/api-surface.txt`.
+- **Pass counters**: `Runtime.counts` (internal, read-only: passes, full passes, safety passes, binding evaluations, view bind functions evaluated and skipped) for the SDK's own tests and benchmark; no behaviour change, nothing new on `Plugin` or `TestHost`.
+- **Benchmark** (`npm run bench`, `scripts/bench.mjs`): a 20,000-row keyed list with 1 % and 10 % row changes through the diff engine, 1,000 passes over 50 bound views and 100 commands, and the state-change-to-send latency; medians of five runs, baseline in `docs/maintaining.md`.
+- **`@vestra-player/sdk/testing` is split into modules** (step 1 of the refactor, batch A). **Who must change: nobody**: no API, behaviour or wire change. The single 7,600-line `src/plugin/testing.ts` is now the directory `src/plugin/testing/`: `index.ts` keeps the module page, every export and the one `TestHost` class with all its public members and doc comments; the class keeps its private state in one internal object (`internals.ts`) and delegates its wire handlers and longer methods to area modules (`transport`, `commands`, `declarations`, `core-actions`, `i18n`, `layout`, `osd`, `jobs`, `processing`, `media`, `services`). Error codes, messages and handler semantics are unchanged: every golden trace and host scenario, the API surface snapshot and the pass counts are identical, and the declarations (`dist/plugin/testing/index.d.ts`) equal the former `dist/plugin/testing.d.ts` apart from relative import paths. The `./testing` export now points at `dist/plugin/testing/index.js`; `dist/plugin/testing.js` stays as a re-export. The documentation tree (`dist/docs-tree.json.gz`) is unchanged.
+
 ## 1.6.17
 
 **Who must change: nobody.** Tables follow the slim context menu (B5): a data refresh of `BUILTIN_COMMANDS`, `BUILTIN_SUBMENUS` and the test host's core commands for the player's right-click menu (player 0.7.6); no API change, `apiVersion` stays `vestra/1`. A plugin whose tests compare a path or a key against the tables sees the player's current ones.
@@ -25,11 +46,13 @@
 - **Wire** (additive): `ui.setMount`, `ui.interaction`, `ui.menu` and `ui.unmount` take an optional `slot` naming the panel (without it: the plugin's only panel; `ui.unmount` without it removes every panel); `ui.callback` and `ui.preparing` carry the panel's `slot`, and `ui.callback` keeps `view: "$mount"`. Older players ignore `slot`.
 - **`BUILTIN_COMMANDS`**: the player's seek, frame and speed actions (`host/seek-backward`, `seek-forward`, `frame-back`, `frame-forward`, `rate-down`, `rate-up`, `rate-normal`) leave Playback ▸ Seek and Speed for the command palette (player 0.7.6, with the playback plugin's panel); their keys and categories stay.
 - **`TestHost`**: `panels` (by slot, in mount order) and `mounted(slot?)`; without a slot `mounted()` returns the only panel and throws when there are several. `panel` stays, as the last panel mounted. The handlers take `slot` as the player does; `ui.interaction` stores the locks without it.
+
 ## 1.6.14
 
 **Who must change: nobody.** A data refresh: `BUILTIN_COMMANDS` lists the built-in capture plugin's commands as the player registers them since its capture tab; no API change, `apiVersion` stays `vestra/1`.
 
 - **`BUILTIN_COMMANDS`**: `vestra.capture` has **Video ▸ Snapshot ▸ Capture…** (Alt+S), which opens its sidebar tab; Save/Copy Rendered Frame, Save Current Frame As…, Export Tasks…, the capture formats, Snapshot Settings…, Snapshot Folder… and Open Snapshot Folder left the menu for the command palette, and new palette commands came: Export Clip Range (Ctrl+Shift+E), Save and Copy Video Frame Only, Show Last Capture in Folder, Copy Last Snapshot, Set Clip Start, Set Clip End and Export Last 30 Seconds (Ctrl+Shift+R). A plugin that checks a key or menu path against the table (`vestra-plugin check`, `TestHost`) sees the player's current ones.
+
 ## 1.6.13
 
 **Who must change: plugin tests that toggle a column in fullscreen.** In fullscreen `toggle()` now only switches the column on or off (user ruling 2026-11-08); a test that asserted `effective: true` after toggling a column on in fullscreen now sees `effective: false`, `reason: "fullscreen"` (on, revealed by the right edge). Plugin code needs no change; `apiVersion` stays `vestra/1`, and the wire gains one optional field.
@@ -45,6 +68,7 @@
 - **`Panel.toggle` and `PanelSlot.toggle` slide a collapsed column out.** In fullscreen a sidebar or adjust column the user wants shown is collapsed at the right edge (`reason: "fullscreen"`). Toggling it then turned it off; it now shows it, which player 0.7.6 answers by sliding the column out, as its own Adjust button and Alt+1…4 do. Toggling a column that is on screen still turns it off. With players before 0.7.6 a show of a collapsed column changes nothing on screen, as before.
 - **[adjust-panel](docs/examples/adjust-panel.md)** declares `events`: without it `plugin.player.state` changes only after the plugin's own calls, so a panel activated before a file was opened stayed disabled at 1×. A new test opens the file after activation. Its presets are four (0.5×, 1×, 1.5×, 2×), which fit the adjust column at its least width. No other example reads `player.state` without `events`.
 - **A development warning for state followed without `events`.** A plugin that registers an `onChange` or a `bind` whose function reads changing state (`player.state`, a panel position, and the like) without the `events` capability gets one line in its log, once per plugin: changes made elsewhere never reach it. Only a warning; behaviour is unchanged. `TestHost` already behaved like the player here (it delivers `source.state` and the other state events only to a plugin that subscribed, which needs `events`): a new test pins that down. The example's old tests passed because they opened the file before starting the plugin or did not check `enabled`. No SDK example or test relied on the opposite, so nobody must change.
+
 ## 1.6.11
 
 **Who must change: nobody.** Additions only: a mount slot, a panel position, a button icon and `TestHost` support; `apiVersion` stays `vestra/1`, no new capability. A plugin that mounts `"adjust"` sets `minPlayerVersion` to `0.7.6`: older players refuse the slot (`invalid`), which fails the activation like any refused mount.

package/dist/plugin/appearance.js

@@ -1,5 +1,5 @@
 /** The player's palette (`plugin.appearance`; `ui.theme` to change it). */
-import { failure } from "./runtime.js";
+import { failure } from "./errors.js";
 import { windowOf } from "./window.js";
 import { LOCALES } from "../i18n.js";
 const preference = (value) => value === "system" || LOCALES.includes(value)

package/dist/plugin/bindings.js

@@ -6,7 +6,7 @@
  *   binding  = { modifier "+" } input        modifiers in order Ctrl, Alt, Shift, Cmd
  *   input    = key | "Mouse:" mouse
  */
-import { failure } from "./runtime.js";
+import { failure } from "./errors.js";
 /**
  * The names a binding (`CommandOptions.bindings`, `Bindings.set`) is made
  * of, as the player's binding parser accepts them. A binding is

package/dist/plugin/commands.js

@@ -1,8 +1,9 @@
 /** Menu commands: declaration, state sync (revisions hidden) and dispatch. */
-import { failure, Latest, quiet, uncertain } from "./runtime.js";
+import { Latest } from "./latest.js";
+import { failure, quiet, uncertain } from "./errors.js";
 import { checkBindings } from "./bindings.js";
 import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, MENU_IDS } from "../commands.js";
-import { ImageHandle } from "./ui.js";
+import { ImageHandle } from "./view/image.js";
 import { isTextValue, textProblem } from "../i18n.js";
 import { conditionJson, isCondition } from "./when.js";
 const value = (item) => typeof item === "function" ? item() : item;

package/dist/plugin/connection.d.ts

@@ -0,0 +1,119 @@
+import type { Json, LocalServices, Transport, Wire } from "../wire.ts";
+import type { App, Disposable, Locale, StopReason, SystemInfo } from "./types.ts";
+/**
+ * Why something listens, for the player's log line that says why a plugin
+ * keeps running (`events.subscribe { why }`, player 0.5.21): computed
+ * only when the player is told.
+ */
+export type Why = () => string;
+/**
+ * Events the player wakes a stopped plugin for (player 0.5.21): a listener
+ * of one does not keep the plugin running. They follow deliberate changes
+ * (an install, a key edit, the palette, a resolver), not playback.
+ */
+export declare const WAKE_EVENTS: readonly string[];
+export interface PluginManifest {
+    id: string;
+    capabilities: string[];
+}
+/** How the plugin is run: the player's runner, or `TestHost`. */
+export interface RuntimeOptions {
+    /**
+     * A declaration the player refuses during activation fails activation
+     * (`startPlugin`, so a plugin's tests show it) instead of being logged,
+     * reported to `onError` and skipped (the player's runner).
+     */
+    strictDeclarations?: boolean;
+}
+/** A stop reason the runner passed on, if this SDK knows it. */
+export declare function stopReason(value: unknown): StopReason | undefined;
+type Listener = (data: unknown) => void;
+/**
+ * Per-plugin connection to the player. Scopes reach it through `Runtime`;
+ * the flat RPC clients stay private here so protocol fields never reach
+ * plugin code.
+ */
+export declare class Connection {
+    #private;
+    readonly host: Wire;
+    readonly manifest: PluginManifest;
+    readonly directory: string;
+    /** Writable per-plugin data directory from the host, if it provided one. */
+    readonly dataDirectory: string | undefined;
+    /** Test doubles for local processes; the real system when absent. */
+    readonly local: LocalServices | undefined;
+    /** Registrations that activation must wait for before reporting ready. */
+    readonly startup: Set<Promise<unknown>>;
+    readonly views: Map<string, (callback: string, args: Json[]) => void>;
+    readonly commands: Map<string, () => void>;
+    readonly services: Map<string, unknown>;
+    /**
+     * Set when the player stops the plugin (`PluginInstance.dispose`), before
+     * the root scope is disposed: `DisposeInfo` and `plugin.stopReason`.
+     */
+    stopping: {
+        reason: StopReason | undefined;
+    } | undefined;
+    /** `plugin.app`, from the start-up handshake; `system()` asks the player. */
+    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, options?: RuntimeOptions);
+    can(capability: string): boolean;
+    /** Lazily created singletons shared by every scope of this plugin. */
+    service<T>(name: string, create: () => T): T;
+    /**
+     * Registrations started while `activate` runs must succeed before the
+     * plugin reports ready; later ones report failures to their scope.
+     */
+    starting<T>(work: Promise<T>, report: (error: unknown) => void): Promise<T>;
+    /**
+     * A declaration the player checks on its own (`what`: "command x"),
+     * started like `starting`. In the player's runner a refusal of it during
+     * activation (`invalid`, `conflict`, `limit`) does not fail the plugin:
+     * it is logged, skipped and reported to the scope once activation
+     * completes, so an `onError` added anywhere in `activate` hears it (SDK
+     * 1.5.49; VS Code logs a bad contribution and activates the extension).
+     * Under `strictDeclarations` (TestHost) it fails activation as before.
+     */
+    declaring<T>(work: Promise<T>, what: string, report: (error: unknown) => void): Promise<T>;
+    activated(): Promise<void>;
+    /**
+     * Where the plugin's code called into the SDK: the first stack frame
+     * outside the SDK, as a path relative to the plugin's directory and a
+     * line (`main.ts:353`). Captured now, formatted when asked.
+     */
+    callSite(): () => string | undefined;
+    /**
+     * Host events with one `events.subscribe` per name, however many listeners.
+     * Without the `events` capability the listener simply never fires.
+     * `mirror`: the SDK's own copy of the state (`plugin.player.state` and
+     * the like), not a listener of the plugin's (see {@link EventGroup}).
+     */
+    on(event: string, listener: Listener, 
+    /** The capability the event needs; `null`: none. */
+    needs?: string | null, mirror?: boolean): Disposable;
+    /**
+     * Count `event` as listened to while held: a watcher of a service's
+     * state, a binding that reads it. Nothing when nothing subscribed to it
+     * (no capability, or the service did not start).
+     */
+    hold(event: string, why?: Why): Disposable;
+    /**
+     * Why the plugin listens to each event it really listens to (mirrors
+     * left out), as the player's log says it: for {@link TestHost} and
+     * `vestra-plugin test`.
+     */
+    listening(): Map<string, string[]>;
+    /** Raw transport events the host pushes without a subscription. */
+    raw(event: string, listener: Listener): Disposable;
+}
+/** `plugin.app` from the start-up handshake (the runner's environment). */
+export declare function appInfo(raw: unknown, system?: () => Promise<SystemInfo>): App;
+export {};

package/dist/plugin/connection.js

@@ -0,0 +1,402 @@
+/**
+ * The plugin's connection to the player (L1, refactor plan §2.2): the
+ * transport and its typed client (`host`), event subscriptions counted per
+ * name with their `why`/`mirror` marks (`on`, `hold`, `raw`), the
+ * activation state machine (`starting`, `declaring`, `activated`) and what
+ * the start-up handshake said (`app`, `locale`, `features`). It knows
+ * nothing of update passes (`passes.ts`); `Runtime` (`runtime.ts`) adds them.
+ */
+import { createWire, HostError } from "../wire.js";
+import { LOCALES } from "../i18n.js";
+import { failure } from "./errors.js";
+import { basename, isAbsolute, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The SDK's own files (`src/` or `dist/`): left out of a call site. */
+const SDK_DIRECTORY = fileURLToPath(new URL("..", import.meta.url));
+/**
+ * Events the player wakes a stopped plugin for (player 0.5.21): a listener
+ * of one does not keep the plugin running. They follow deliberate changes
+ * (an install, a key edit, the palette, a resolver), not playback.
+ */
+export const WAKE_EVENTS = [
+    "packages.changed",
+    "bindings.changed",
+    // Player 0.7.6: sent to a plugin whose own keys changed and, from SDK
+    // 1.6.16, to every listener when a player command (`host/<id>`) is
+    // rebound, which wakes each parked listener.
+    "commands.keys",
+    "appearance.changed",
+    "resolvers.fileTypes",
+];
+/**
+ * The player's answers to a declaration that refuse that one declaration
+ * (a command's path, texts or count): during activation they skip it
+ * instead of failing the plugin (`Connection.declaring`, SDK 1.5.49).
+ */
+const DECLARATION_REFUSALS = new Set([
+    "invalid",
+    "conflict",
+    "limit",
+]);
+/** The reasons `StopReason` names; anything else reads as `undefined`. */
+const STOP_REASONS = new Set([
+    "quit",
+    "disable",
+    "uninstall",
+    "reload",
+    "upgrade",
+    "idle",
+    "failed",
+    "host-lost",
+]);
+/** A stop reason the runner passed on, if this SDK knows it. */
+export function stopReason(value) {
+    return typeof value === "string" && STOP_REASONS.has(value)
+        ? value
+        : undefined;
+}
+/**
+ * Per-plugin connection to the player. Scopes reach it through `Runtime`;
+ * the flat RPC clients stay private here so protocol fields never reach
+ * plugin code.
+ */
+export class Connection {
+    host;
+    manifest;
+    directory;
+    /** Writable per-plugin data directory from the host, if it provided one. */
+    dataDirectory;
+    /** Test doubles for local processes; the real system when absent. */
+    local;
+    /** Registrations that activation must wait for before reporting ready. */
+    startup = new Set();
+    #activating = true;
+    /** `RuntimeOptions.strictDeclarations`. */
+    #strict;
+    /** Declarations skipped during activation: reported once it completes. */
+    #refusals = [];
+    #transport;
+    #events = new Map();
+    /** The missing `events` warning was given (once per plugin). */
+    #warnedEvents = false;
+    views = new Map();
+    commands = new Map();
+    services = new Map();
+    /**
+     * Set when the player stops the plugin (`PluginInstance.dispose`), before
+     * the root scope is disposed: `DisposeInfo` and `plugin.stopReason`.
+     */
+    stopping;
+    /** `plugin.app`, from the start-up handshake; `system()` asks the player. */
+    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, options = {}) {
+        this.#transport = transport;
+        this.#strict = options.strictDeclarations ?? false;
+        this.dataDirectory = dataDirectory;
+        this.local = transport.local;
+        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";
+        this.manifest = manifest;
+        this.directory = directory;
+        transport.on("ui.callback", (data) => {
+            const event = data;
+            // A panel's callback names its slot (player 0.7.6: one panel per
+            // slot); older players name only `"$mount"`, and the plugin has one.
+            const view = event.view === "$mount"
+                ? event.slot
+                    ? `panel:${event.slot}`
+                    : [...this.views.keys()].find((key) => key.startsWith("panel:"))
+                : event.view;
+            if (view)
+                this.views.get(view)?.(event.callback, event.args);
+        });
+        transport.on("commands.execute", (data) => {
+            this.commands.get(data.id)?.();
+        });
+    }
+    can(capability) {
+        return this.manifest.capabilities.includes(capability);
+    }
+    /** Lazily created singletons shared by every scope of this plugin. */
+    service(name, create) {
+        if (!this.services.has(name))
+            this.services.set(name, create());
+        return this.services.get(name);
+    }
+    /**
+     * Registrations started while `activate` runs must succeed before the
+     * plugin reports ready; later ones report failures to their scope.
+     */
+    starting(work, report) {
+        if (this.#activating)
+            this.startup.add(work);
+        else
+            work.catch(report);
+        work.catch(() => { });
+        return work;
+    }
+    /**
+     * A declaration the player checks on its own (`what`: "command x"),
+     * started like `starting`. In the player's runner a refusal of it during
+     * activation (`invalid`, `conflict`, `limit`) does not fail the plugin:
+     * it is logged, skipped and reported to the scope once activation
+     * completes, so an `onError` added anywhere in `activate` hears it (SDK
+     * 1.5.49; VS Code logs a bad contribution and activates the extension).
+     * Under `strictDeclarations` (TestHost) it fails activation as before.
+     */
+    declaring(work, what, report) {
+        if (!this.#activating || this.#strict)
+            return this.starting(work, report);
+        const settled = work.then(() => { }, (error) => {
+            if (!(error instanceof HostError) ||
+                !DECLARATION_REFUSALS.has(error.code))
+                throw error;
+            console.error(`[${this.manifest.id}] ${what} skipped, the player refused it (${error.code}): ${error.message}`);
+            this.#refusals.push(() => report(error));
+        });
+        // Observed now: `activated()` may come after `activate` awaits, and
+        // its `allSettled` still sees the rejection.
+        settled.catch(() => { });
+        this.startup.add(settled);
+        work.catch(() => { });
+        return work;
+    }
+    async activated() {
+        while (this.startup.size) {
+            const pending = [...this.startup];
+            this.startup.clear();
+            for (const result of await Promise.allSettled(pending))
+                if (result.status === "rejected")
+                    throw result.reason;
+        }
+        this.#activating = false;
+        for (const report of this.#refusals.splice(0))
+            report();
+    }
+    /**
+     * Where the plugin's code called into the SDK: the first stack frame
+     * outside the SDK, as a path relative to the plugin's directory and a
+     * line (`main.ts:353`). Captured now, formatted when asked.
+     */
+    callSite() {
+        const limit = Error.stackTraceLimit;
+        Error.stackTraceLimit = 40;
+        const error = new Error();
+        Error.stackTraceLimit = limit;
+        let site = null;
+        return () => {
+            if (site === null)
+                site = this.#site(error.stack ?? "");
+            return site;
+        };
+    }
+    #site(stack) {
+        for (const line of stack.split("\n").slice(1)) {
+            const match = /\(?((?:file:\/\/)?[^()\s]+?):(\d+):\d+\)?\s*$/.exec(line);
+            if (!match)
+                continue;
+            let file = match[1];
+            if (file.startsWith("file:"))
+                try {
+                    file = fileURLToPath(file);
+                }
+                catch {
+                    continue;
+                }
+            const sdk = relative(SDK_DIRECTORY, file);
+            if (!isAbsolute(file) || !(sdk.startsWith("..") || isAbsolute(sdk)))
+                continue;
+            const inside = relative(this.directory, file);
+            const shown = inside.startsWith("..") || isAbsolute(inside) ? basename(file) : inside;
+            return `${shown.replaceAll("\\", "/")}:${match[2]}`;
+        }
+        return undefined;
+    }
+    /**
+     * Host events with one `events.subscribe` per name, however many listeners.
+     * Without the `events` capability the listener simply never fires.
+     * `mirror`: the SDK's own copy of the state (`plugin.player.state` and
+     * the like), not a listener of the plugin's (see {@link EventGroup}).
+     */
+    on(event, listener, 
+    /** The capability the event needs; `null`: none. */
+    needs = "events", mirror = false) {
+        let entry = this.#events.get(event);
+        const created = !entry;
+        if (!entry) {
+            entry = { listeners: new Set(), active: 0, whys: new Map() };
+            this.#events.set(event, entry);
+        }
+        const group = entry;
+        group.listeners.add(listener);
+        const token = {};
+        if (!mirror) {
+            group.active++;
+            group.whys.set(token, listenerWhy(this.callSite()));
+        }
+        if (created && needs === "events" && !this.can(needs))
+            group.unheard = true;
+        if (!mirror && group.unheard)
+            this.#warnUnheard(event);
+        if (created && (needs === null || this.can(needs))) {
+            group.told = group.active > 0;
+            const whys = group.told ? allWhys(group) : undefined;
+            group.toldWhy = whys?.join("\n");
+            group.off = this.host.events.subscribe(event, (data) => {
+                for (const each of [...group.listeners])
+                    each(data);
+            }, !group.told, whys);
+            this.starting(group.off, (error) => console.error(`[${this.manifest.id}] subscribe ${event}:`, error));
+        }
+        else
+            this.#tell(event, group);
+        let listening = true;
+        return {
+            dispose: async () => {
+                if (!listening)
+                    return;
+                listening = false;
+                group.listeners.delete(listener);
+                if (!mirror)
+                    group.active--;
+                group.whys.delete(token);
+                if (this.#events.get(event) !== group)
+                    return;
+                if (group.listeners.size)
+                    return this.#tell(event, group);
+                this.#events.delete(event);
+                const off = await group.off?.catch(() => undefined);
+                await off?.().catch(() => { });
+            },
+        };
+    }
+    /**
+     * Count `event` as listened to while held: a watcher of a service's
+     * state, a binding that reads it. Nothing when nothing subscribed to it
+     * (no capability, or the service did not start).
+     */
+    hold(event, why) {
+        const group = this.#events.get(event);
+        if (!group)
+            return { dispose: async () => { } };
+        if (group.unheard)
+            this.#warnUnheard(event);
+        group.active++;
+        const token = {};
+        group.whys.set(token, why ?? listenerWhy(this.callSite()));
+        this.#tell(event, group);
+        let held = true;
+        return {
+            dispose: async () => {
+                if (!held)
+                    return;
+                held = false;
+                group.active--;
+                group.whys.delete(token);
+                if (this.#events.get(event) === group)
+                    this.#tell(event, group);
+            },
+        };
+    }
+    /**
+     * A development warning, once per plugin, no behaviour change (SDK
+     * 1.6.12): the plugin follows `event` (an `onChange`, a `bind` that reads
+     * the state) without the `events` capability, so changes made elsewhere
+     * (the user, the player, another plugin) never reach it; the state moves
+     * only after its own calls.
+     */
+    #warnUnheard(event) {
+        if (this.#warnedEvents)
+            return;
+        this.#warnedEvents = true;
+        console.warn(`[${this.manifest.id}] follows ${event} (onChange, or a bind() that reads the state) without the "events" capability: changes made elsewhere will not reach it, only its own calls refresh the state. Declare "events" in manifest.json.`);
+    }
+    /**
+     * Tell the player when `group` changes between mirror and listener, and
+     * why it listens when that changed.
+     */
+    #tell(event, group) {
+        const off = group.off;
+        if (!off)
+            return;
+        const active = group.active > 0;
+        const whys = active ? allWhys(group) : undefined;
+        const why = whys?.join("\n");
+        if (group.told === active && group.toldWhy === why)
+            return;
+        group.told = active;
+        group.toldWhy = why;
+        // Part of activation while it runs: the player classifies the plugin
+        // at its ready, which must see this mark. A failure is not one of
+        // activation (an older player never refuses it).
+        const told = off
+            .then(() => this.host.events.listen(event, active, whys))
+            .catch(() => { });
+        this.starting(told, () => { });
+    }
+    /**
+     * Why the plugin listens to each event it really listens to (mirrors
+     * left out), as the player's log says it: for {@link TestHost} and
+     * `vestra-plugin test`.
+     */
+    listening() {
+        const result = new Map();
+        for (const [event, group] of this.#events)
+            if (group.active > 0)
+                result.set(event, allWhys(group));
+        return result;
+    }
+    /** Raw transport events the host pushes without a subscription. */
+    raw(event, listener) {
+        const off = this.#transport.on(event, listener);
+        return { dispose: async () => off() };
+    }
+}
+/** A plugin listener's reason: where it was added. */
+const listenerWhy = (site) => () => {
+    const at = site();
+    return at ? `a listener added at ${at}` : "a listener";
+};
+/** Every active holder's reason in `group`, in the order they came, once each. */
+function allWhys(group) {
+    return [...new Set([...group.whys.values()].map((why) => why()))];
+}
+/** `plugin.app` from the start-up handshake (the runner's environment). */
+export function appInfo(raw, system = () => Promise.reject(failure("unavailable", "no player to ask"))) {
+    const info = (raw ?? {});
+    const parts = (info.components ?? {});
+    const text = (value) => (typeof value === "string" ? value : null);
+    const libav = {};
+    for (const [name, version] of Object.entries(parts.libav ?? {}))
+        if (typeof version === "string")
+            libav[name] = version;
+    const app = {
+        version: text(info.version) ?? "0.0.0",
+        build: text(info.build),
+        components: Object.freeze({
+            mpv: text(parts.mpv),
+            libav: Object.freeze(libav),
+            slint: text(parts.slint) ?? "",
+        }),
+    };
+    // A method, not data: kept out of comparisons and JSON of the facts.
+    Object.defineProperty(app, "system", { value: system, enumerable: false });
+    return Object.freeze(app);
+}

package/dist/plugin/drops.d.ts

@@ -1,4 +1,4 @@
-import type { Runtime } from "./runtime.ts";
+import type { Connection } from "./connection.ts";
 import type { ScopeImpl } from "./scope.ts";
 import type { Disposable, DropModifiers, Drops } from "./types.ts";
 type PanelDrop = {
@@ -16,11 +16,11 @@ type PanelDrop = {
 declare class DropService {
     #private;
     readonly handlers: Map<string, (paths: string[], modifiers: DropModifiers) => void>;
-    constructor(runtime: Runtime);
+    constructor(runtime: Connection);
     id(): string;
     /** The first listener asks the player for panel drops; the last stops them. */
     listen(scope: ScopeImpl, listener: (drop: PanelDrop) => void): Disposable;
 }
-export declare const dropsOf: (runtime: Runtime) => DropService;
+export declare const dropsOf: (runtime: Connection) => DropService;
 export declare const drops: (scope: ScopeImpl) => Drops;
 export {};

package/dist/plugin/drops.js

@@ -1,5 +1,5 @@
 /** File drops (`plugin.drops`, `Panel.onDrop`; capability `ui.drop`). */
-import { failure } from "./runtime.js";
+import { failure } from "./errors.js";
 const modifiers = (raw) => Object.freeze({
     alt: raw?.alt === true,
     shift: raw?.shift === true,

package/dist/plugin/errors.d.ts

@@ -0,0 +1,9 @@
+import type { PluginError } from "./types.ts";
+export declare const sleep: (ms: number) => Promise<void>;
+export declare function toError(error: unknown): PluginError;
+export declare const failure: (code: string, message?: string) => PluginError;
+/** Host replies are definite; anything else (lost reply, client timeout) is not. */
+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>;
+export declare function abortError(): PluginError;