@vestra-player/sdk 1.6.18 → 1.6.19

package/CHANGELOG.md

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

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;

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 };