@vestra-player/sdk 1.5.36 → 1.5.38

package/dist/plugin/testing.js

@@ -268,7 +268,8 @@ const MAX_SIDEBAR_TABS = 8;
  *   {@link TestHost.app}, {@link TestHost.systemInfo},
  *   {@link TestHost.chapters}, {@link TestHost.audioDevices},
  *   {@link TestHost.secrets}, {@link TestHost.clipboard},
- *   {@link TestHost.tools}, {@link TestHost.rendering}.
+ *   {@link TestHost.tools}, {@link TestHost.rendering},
+ *   {@link TestHost.upscaling}.
  * - **Assert** on records: {@link TestHost.osd}, {@link TestHost.calls},
  *   {@link TestHost.sent}, {@link TestHost.conflicts},
  *   {@link TestHost.layout}, {@link TestHost.menus}, and many more.
@@ -332,6 +333,16 @@ export class TestHost {
     calls = [];
     /** The host events the plugin subscribed to (needs `events` etc.). */
     subscriptions = new Set();
+    /**
+     * The subscribed events the plugin really listens to: an `onChange` and
+     * the like, or a binding that reads the state. The SDK's own copies of
+     * the state (what keeps `plugin.player.state` current) are left out.
+     * Empty means the player may stop the plugin while nothing uses it
+     * (unless it holds something else: a window, a panel, a filter…).
+     *
+     * @since 1.5.38
+     */
+    listening = new Set();
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with
@@ -1622,6 +1633,60 @@ export class TestHost {
         gpu: { available: true, reason: null },
         restarts: 0,
     };
+    /**
+     * The GPU's video upscaler behind `plugin.video.upscaling` (player
+     * 0.5.16), answered as the player would:
+     *
+     * - `state()` and `set(true)` set `checked` (the player's one GPU check; a
+     *   plugin that should not wake the GPU while it starts can assert it is
+     *   still `false`) and report `available` from `reason` (`null`: it
+     *   works), this plugin's `enabled`, and `requested` with `factor` while
+     *   enabled, available and `factor` is above 1.
+     * - `set(true)` refuses with `unsupported` and the reason's message while
+     *   `reason` is set, unless its code is `decoding`, or `rendering` with
+     *   `renderingStarting` (GPU rendering still starting): those can pass
+     *   during the run, so the player keeps the request. Nothing changes when
+     *   it refuses.
+     * - `set(false)` always succeeds and does not check the GPU: before any
+     *   check it reports `available: false` with the reason `unchecked`.
+     *
+     * Inject other answers with `host.handle("video.upscaling.set", …)`. The
+     * defaults are a player where upscaling works and a 1080p video shown
+     * full screen on a 4K display (`factor` 2), whatever `systemInfo` says.
+     *
+     * @example Test the menu item on a computer without an RTX GPU
+     * The plugin's upscaling item is greyed out with the player's reason after
+     * the user first picks it. Starting the plugin checks nothing (`checked`
+     * stays false, so no GPU wakes up); the first pick reads the state, and
+     * `set(true)` would reject with `unsupported`, as in the player.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+     * import activate from "../main.ts";
+     *
+     * const host = new TestHost();
+     * host.upscaling.reason = { code: "no-gpu", message: "no NVIDIA GPU" };
+     * const { stop } = await startPlugin(activate, {
+     *   directory: new URL("..", import.meta.url),
+     *   host,
+     * });
+     * assert.equal(host.upscaling.checked, false); // starting woke no GPU
+     * const item = host.command("upscaling");
+     * await item.run(); // the first pick checks the GPU
+     * assert.equal(item.state.enabled, false); // greyed out
+     * assert.equal(item.state.reason, "no NVIDIA GPU"); // the player's message
+     * await stop();
+     * ```
+     *
+     * @since 1.5.37
+     */
+    upscaling = {
+        reason: null,
+        enabled: false,
+        factor: 2,
+        checked: false,
+        renderingStarting: false,
+    };
     /** What `player.chapters()` lists while media is ready. */
     chapters = [];
     #overrides = new Map();
@@ -3252,6 +3317,27 @@ export class TestHost {
             revision: stamp.revision + 1,
         };
     }
+    /** `video.upscaling.state` from {@link TestHost.upscaling}. */
+    #upscalingState(check = true) {
+        if (check)
+            this.upscaling.checked = true;
+        const { enabled, factor } = this.upscaling;
+        // `set(false)` before any check: the player answers without checking.
+        const reason = this.upscaling.checked
+            ? this.upscaling.reason
+            : {
+                code: "unchecked",
+                message: "the player has not checked the GPU yet; state() or set(true) checks it",
+            };
+        const requested = enabled && reason === null && factor !== null && factor > 1;
+        return {
+            available: reason === null,
+            reason: reason ? { ...reason } : null,
+            enabled,
+            requested,
+            factor: requested ? factor : null,
+        };
+    }
     /** `rendering.state` from {@link TestHost.rendering} and `videoRender.gpu`. */
     #renderingState() {
         const { reason, preference, startedWith, gpu } = this.rendering;
@@ -3301,8 +3387,18 @@ export class TestHost {
         };
     }
     #defaults = {
-        "events.subscribe": (p) => void this.subscriptions.add(String(p.event)),
-        "events.unsubscribe": (p) => void this.subscriptions.delete(String(p.event)),
+        "events.subscribe": (p) => {
+            const event = String(p.event);
+            this.subscriptions.add(event);
+            if (p.mirror === true)
+                this.listening.delete(event);
+            else
+                this.listening.add(event);
+        },
+        "events.unsubscribe": (p) => {
+            this.subscriptions.delete(String(p.event));
+            this.listening.delete(String(p.event));
+        },
         "commands.register": (p) => {
             const id = String(p.id);
             // The player's built-in menu ids (MENU_IDS) in the first path segment.
@@ -3640,6 +3736,26 @@ export class TestHost {
             this.rendering.restarts++;
             return null;
         },
+        // As the player 0.5.16 (see TestHost.upscaling for the model).
+        "video.upscaling.state": () => this.#upscalingState(),
+        "video.upscaling.set": (p) => {
+            if (typeof p.enabled !== "boolean")
+                throw new HostError("invalid", "enabled must be a boolean");
+            const { reason, renderingStarting } = this.upscaling;
+            // Off: always, without the GPU check.
+            if (!p.enabled) {
+                this.upscaling.enabled = false;
+                return this.#upscalingState(false);
+            }
+            const passes = reason?.code === "decoding" ||
+                (reason?.code === "rendering" && renderingStarting);
+            if (reason && !passes) {
+                this.upscaling.checked = true;
+                throw new HostError("unsupported", `video upscaling cannot work here: ${reason.message}`);
+            }
+            this.upscaling.enabled = true;
+            return this.#upscalingState();
+        },
         "clipboard.readText": () => this.clipboard.text,
         "clipboard.writeText": (p) => {
             if (typeof p.text !== "string")

package/dist/plugin/timeline.d.ts

@@ -16,7 +16,7 @@ export declare class TimelineService {
     accept(marks: WireMark[]): void;
     read(): Promise<void>;
     watch(listener: (marks: readonly TimelineMark[]) => void): {
-        dispose: () => Promise<undefined>;
+        dispose: () => Promise<void>;
     };
 }
 export declare const timelineOf: (runtime: Runtime) => TimelineService;

package/dist/plugin/timeline.js

@@ -27,13 +27,14 @@ export class TimelineService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("timeline.changed", (data) => {
             const marks = data?.marks;
             if (Array.isArray(marks))
                 this.accept(marks);
             else
                 void this.read();
-        });
+        }, "events", true);
     }
     accept(marks) {
         const next = view(marks);
@@ -51,7 +52,13 @@ export class TimelineService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("timeline.changed");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 export const timelineOf = (runtime) => runtime.service("timeline", () => new TimelineService(runtime));
@@ -60,6 +67,7 @@ export function timeline(scope) {
     return {
         get marks() {
             service().start();
+            scope.runtime.reading("timeline.changed");
             return service().marks;
         },
         onChange(listener) {

package/dist/plugin/types.d.ts

@@ -213,10 +213,11 @@ export interface Scope extends Disposable {
     /** Playback state and controls (`playback.read`, `events`, `playback.control`). */
     readonly player: Player;
     /**
-     * Video processing: this plugin's filter chain, the display layer and the
-     * GPU render options. All three need `processing.video` and
-     * `playback.read`; the filter chain also needs `events` (without it the
-     * SDK never sees the media become ready and the chain stays `waiting`).
+     * Video processing: this plugin's filter chain, the display layer, the
+     * GPU render options and the GPU's video upscaler. The first three need
+     * `processing.video` and `playback.read`; the filter chain also needs
+     * `events` (without it the SDK never sees the media become ready and the
+     * chain stays `waiting`). The upscaler needs `video.upscaling` only.
      */
     readonly video: {
         /**
@@ -249,6 +250,12 @@ export interface Scope extends Disposable {
          *   while the first handle is not disposed.
          */
         render(): RenderOptions;
+        /**
+         * The GPU's video upscaler (NVIDIA RTX Video Super Resolution on
+         * Windows; needs `video.upscaling`, player 0.5.16): whether it works
+         * here and why not, and turning it on or off for this plugin.
+         */
+        readonly upscaling: VideoUpscaling;
     };
     /**
      * Audio processing: this plugin's filter chain and delay
@@ -6439,6 +6446,270 @@ export interface RenderOptions extends Disposable {
      */
     onStatus(listener: (status: FilterStatus) => void): Disposable;
 }
+/**
+ * Why the GPU's video upscaler does not work, as a stable kebab-case code.
+ * A newer player may add codes: compare with the ones you handle and show
+ * {@link UpscalingReason.message} for the rest. The codes of player 0.5.16,
+ * in the order the player checks them (the first that holds is reported):
+ *
+ * | Code | Meaning |
+ * | --- | --- |
+ * | `platform` | The player has no video upscaler on this system (macOS, Linux). |
+ * | `no-gpu` | No GPU that can upscale video (Windows: no NVIDIA GPU). |
+ * | `driver` | The graphics driver is too old (Windows: an NVIDIA driver before 530). |
+ * | `gpu-unsupported` | The driver does not offer upscaling on this GPU (Windows: not an RTX GPU), or the check failed. |
+ * | `rendering` | The player renders in software, or GPU rendering is still starting; upscaling needs GPU rendering ({@link Rendering}). |
+ * | `adapter` | GPU rendering runs on another GPU than the one that can upscale (a laptop with two GPUs; Windows: choose the high-performance GPU for Vestra in Settings ▸ System ▸ Display ▸ Graphics). |
+ * | `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a {@link VideoFilter} needs the frames in memory. |
+ * | `unchecked` | The player has not checked the GPU yet. Only in the answer to `set(false)`, which never starts the check; `state()` and `set(true)` always check first. |
+ *
+ * `decoding` and `rendering` while GPU rendering is still starting can pass
+ * during the run, so `set(true)` accepts them and keeps the request; every
+ * other reason holds until the player restarts, and `set(true)` rejects it.
+ * Turning upscaling off is always accepted.
+ *
+ * @example Advise the user by reason
+ * The plugin shows its own advice for the reasons the user can act on and
+ * the player's message for the rest. `reason.code` is looked up among the
+ * codes the plugin knows; an unknown code from a newer player falls
+ * through to the message, which names the GPU and what to do.
+ * ```ts
+ * const { reason } = await plugin.video.upscaling.state();
+ * // Advice for the codes this plugin knows; any other code shows the message.
+ * const advice: Partial<Record<UpscalingReasonCode, string>> = {
+ *   driver: "Update the NVIDIA driver to 530 or newer.",
+ *   rendering: "Turn on Video ▸ GPU Rendering (Experimental) and restart.",
+ * };
+ * if (reason) console.log(advice[reason.code] ?? reason.message);
+ * ```
+ *
+ * @player 0.5.16
+ * @since 1.5.37
+ * @category Processing
+ */
+export type UpscalingReasonCode = "platform" | "no-gpu" | "driver" | "gpu-unsupported" | "rendering" | "adapter" | "decoding" | "unchecked" | (string & {});
+/**
+ * Why the GPU's video upscaler does not work: a stable
+ * {@link UpscalingReasonCode} to branch on and a sentence to show, the same
+ * shape as {@link RenderingReason}.
+ *
+ * @example Grey out a menu item with the player's reason
+ * The plugin disables its upscaling item and shows why. `message` is the
+ * player's English text, naming the GPU and what the user can do (turn on
+ * GPU rendering, choose the other GPU, update the driver); `code` is for
+ * decisions.
+ * ```ts
+ * const { available, reason } = await plugin.video.upscaling.state();
+ * if (!available && reason) console.log(`${reason.code}: ${reason.message}`);
+ * ```
+ *
+ * @player 0.5.16
+ * @since 1.5.37
+ * @category Processing
+ */
+export interface UpscalingReason {
+    /** The reason as a stable kebab-case code; branch on this. */
+    readonly code: UpscalingReasonCode;
+    /**
+     * The reason as English text for people, for example with the GPU's name
+     * and what to change; never branch on it.
+     */
+    readonly message: string;
+}
+/**
+ * What {@link VideoUpscaling.state} and {@link VideoUpscaling.set} report:
+ * whether the upscaler works now and why not, whether this plugin turned
+ * it on, and whether the player asked the GPU to upscale.
+ *
+ * @remarks
+ * `requested` is as far as the player can see. The player puts the
+ * upscaler last in the video filter chain, scaling the video to the area it
+ * is shown in; the driver gives no sign that it upscales. On Windows the
+ * user must also turn on Super Resolution in the NVIDIA app (System ▸ Video
+ * ▸ RTX Video Enhancement), which no program can read: say so next to the
+ * switch.
+ *
+ * @example Label the item with what happens now
+ * The plugin's menu item says whether upscaling is on and whether the
+ * video is being upscaled. `enabled` is this plugin's own request;
+ * `requested` is true while the player has the upscaler in the filter
+ * chain, which needs a video shown larger than its own size (`factor`
+ * above 1).
+ * ```ts
+ * const state = await plugin.video.upscaling.state();
+ * // `enabled`: this plugin's request; `requested`: in the filter chain now.
+ * const label = !state.enabled
+ *   ? "AI Upscaling: Off"
+ *   : state.requested
+ *     ? `AI Upscaling: On (×${state.factor?.toFixed(2)})`
+ *     : "AI Upscaling: On (not needed for this video)";
+ * console.log(label);
+ * ```
+ *
+ * @player 0.5.16
+ * @since 1.5.37
+ * @category Processing
+ */
+export interface UpscalingState {
+    /** Whether the upscaler works now; `false` with {@link UpscalingState.reason}. */
+    readonly available: boolean;
+    /** Why it does not work now; `null` while it does. */
+    readonly reason: UpscalingReason | null;
+    /** This plugin asked for upscaling ({@link VideoUpscaling.set}) and has not turned it off. */
+    readonly enabled: boolean;
+    /**
+     * The player has the upscaler in the video filter chain now, for this
+     * plugin or another one: upscaling is enabled and available and the
+     * video is shown larger than its own size. Not a sign that the GPU
+     * upscales (see the remarks).
+     */
+    readonly requested: boolean;
+    /**
+     * The scale factor the upscaler was asked for (the area the video is
+     * shown in over the video's size, in hundredths, above 1); `null` while
+     * nothing is requested.
+     */
+    readonly factor: number | null;
+}
+/**
+ * `plugin.video.upscaling`: the GPU's video upscaler, NVIDIA RTX Video
+ * Super Resolution on Windows (`video.upscaling`). Read whether it works
+ * here and why not; turn it on or off for this plugin.
+ *
+ * @remarks
+ * The player checks the GPU once, when a plugin first asks, and keeps the
+ * answer: the check wakes a sleeping discrete GPU, so call
+ * {@link VideoUpscaling.state} when the plugin first needs the answer (the
+ * first time the user picks its upscaling item), not while the plugin
+ * starts, and do not poll it. `set(false)` never starts the check. It works
+ * only with GPU rendering, on the GPU the upscaler runs on, with the video decoded on that GPU; {@link UpscalingReasonCode}
+ * lists what can stand in the way.
+ *
+ * While some plugin has it on and it works, the player puts the upscaler
+ * last in the video filter chain and scales the video to the area it is
+ * shown in, following window and video size changes (a resize waits until
+ * the size holds). A video already shown at its own size or smaller is not
+ * upscaled. The upscaler stays while any plugin has it on; it goes when the
+ * last one turns it off or stops: the player revokes a stopped plugin's
+ * request.
+ *
+ * **Windows:** the user must turn on Super Resolution in the NVIDIA app
+ * (System ▸ Video ▸ RTX Video Enhancement); no program can read that
+ * switch, and the driver gives no sign that it upscales
+ * ({@link UpscalingState.requested} is as far as the player can see). It
+ * uses the NVIDIA GPU, so power use and heat go up, and on a laptop with
+ * two GPUs the whole player must run on the NVIDIA one.
+ * **macOS, Linux:** `available` is `false` with `platform`.
+ *
+ * Players before 0.5.16 do not know `video.upscaling` and do not load a
+ * plugin that declares it: declare `"minPlayerVersion": "0.5.16"`.
+ *
+ * @example Offer AI upscaling as a menu item
+ * A Video menu item turns upscaling on and off; once the player said it
+ * cannot work here, the item is greyed out with the player's reason. The
+ * state is read the first time the user picks the item (that runs the
+ * player's GPU check, so nothing wakes the GPU while the plugin starts) and
+ * again after each pick; `set` resolves with the new state, or rejects with
+ * `unsupported` where upscaling cannot work in this run.
+ * ```ts
+ * let state: UpscalingState | null = null; // unknown until first picked
+ * plugin.commands.add({
+ *   id: "upscaling",
+ *   path: ["@video", "AI Upscaling"],
+ *   checked: () => state?.enabled ?? false,
+ *   // Greyed only once the player said it cannot work (`decoding` can pass).
+ *   enabled: () => state === null || state.available || state.reason?.code === "decoding",
+ *   reason: () => state?.reason?.message ?? null, // shown while disabled
+ *   run: async () => {
+ *     state ??= await plugin.video.upscaling.state(); // the first pick checks the GPU
+ *     try {
+ *       state = await plugin.video.upscaling.set(!(state?.enabled ?? false));
+ *     } catch (error) {
+ *       // Cannot work in this run (no RTX GPU, software rendering…).
+ *       if ((error as PluginError).code !== "unsupported") throw error;
+ *       state = await plugin.video.upscaling.state();
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @capability video.upscaling
+ * @player 0.5.16; older players do not load a plugin that declares
+ * `video.upscaling`.
+ * @since 1.5.37
+ * @category Processing
+ */
+export interface VideoUpscaling {
+    /**
+     * Read whether the upscaler works now and why not, whether this plugin
+     * turned it on and what the player asked the GPU for.
+     *
+     * @capability video.upscaling
+     * @returns The state, once the player's GPU check ran (the first call
+     *   starts it and may take a moment).
+     * @throws `capability` (rejects) The manifest does not declare
+     *   `video.upscaling`.
+     *
+     * @example Find out whether upscaling can work here
+     * The plugin reads the state the first time the user picks its upscaling
+     * item and keeps it for the item. The first call makes the player check the GPU (which
+     * wakes a sleeping discrete GPU) and later calls reuse the answer; the
+     * rest (GPU rendering, the GPU it runs on, the decoding) is read at
+     * each call.
+     * ```ts
+     * const { available, reason } = await plugin.video.upscaling.state();
+     * if (!available) console.log(reason?.message);
+     * ```
+     *
+     * @since 1.5.37
+     */
+    state(): Promise<UpscalingState>;
+    /**
+     * Turn upscaling on or off for this plugin.
+     *
+     * @remarks
+     * On stays this plugin's request until it turns it off or stops; the
+     * player upscales whenever the request can take effect (a `decoding`
+     * reason can pass with the next file). Off takes the upscaler out at
+     * once unless another plugin has it on. Upscaling is a request of the
+     * whole plugin, not of a {@link Scope}: disposing a scope does not turn
+     * it off.
+     *
+     * @capability video.upscaling
+     * @param enabled - `true` to ask for upscaling, `false` to withdraw the
+     *   request.
+     * @returns The new state.
+     * @throws `capability` (rejects) The manifest does not declare
+     *   `video.upscaling`.
+     * @throws `invalid` (rejects) `enabled` is not a boolean.
+     * @throws `unsupported` (rejects) `true` where upscaling cannot work in
+     *   this run: every {@link UpscalingReasonCode} except `decoding`, and
+     *   except `rendering` while GPU rendering is still starting (those two
+     *   are accepted and the request is kept until they pass); `message` is
+     *   the reason. Nothing changes. `false` is always accepted and answered
+     *   at once without the GPU check (before any check, `available` is
+     *   `false` with `unchecked`).
+     *
+     * @example Turn upscaling on and explain what is needed
+     * The plugin turns upscaling on from its settings and tells the user what
+     * else to switch on. `set(true)` records the request and resolves with the
+     * new state; where upscaling cannot work in this run it rejects with
+     * `unsupported` and the player's reason instead.
+     * ```ts
+     * try {
+     *   const state = await plugin.video.upscaling.set(true);
+     *   // The driver's own switch cannot be read: remind the user once.
+     *   if (state.enabled) await plugin.osd.show("Turn on Super Resolution in the NVIDIA app");
+     * } catch (error) {
+     *   if ((error as PluginError).code !== "unsupported") throw error;
+     *   await plugin.osd.show("AI upscaling: {}", [(error as PluginError).message]);
+     * }
+     * ```
+     *
+     * @since 1.5.37
+     */
+    set(enabled: boolean): Promise<UpscalingState>;
+}
 /**
  * A subtitle track of the current source.
  *
@@ -7700,6 +7971,17 @@ export interface PluginInfo {
      * @since 1.5.9
      */
     display?: PluginDisplay;
+    /**
+     * For `state: "running"`: `"running"` while its process runs, `"idle"`
+     * while the player stopped it because nothing used it (lazy activation:
+     * it starts again on its next use, its menu items, keys, settings pages,
+     * resolvers and drop targets stay). Absent in other states and from
+     * players before 0.5.18. A change between the two alone does not fire
+     * {@link Packages.onChange}.
+     *
+     * @since 1.5.38
+     */
+    process?: "running" | "idle";
 }
 /**
  * {@link PluginInfo.display}: a package's `name`, `punchline`,

package/dist/plugin/ui.js

@@ -534,13 +534,20 @@ class LayoutService {
         if (this.#started || !this.#runtime.can("ui.mount"))
             return;
         this.#started = true;
-        this.#runtime.on("window.state", () => void this.read());
+        // A mirror: panels listen through `watch`.
+        this.#runtime.on("window.state", () => void this.read(), "events", true);
         void this.read();
     }
     watch(listener) {
         this.start();
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("window.state");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
     async read() {
         if (this.#reading) {

package/dist/plugin/window.d.ts

@@ -26,7 +26,7 @@ export declare class WindowService {
     accept(facts: WindowFacts): void;
     read(): Promise<void>;
     watch(listener: (state: WindowState) => void): {
-        dispose: () => Promise<undefined>;
+        dispose: () => Promise<void>;
     };
 }
 export declare const windowOf: (runtime: Runtime) => WindowService;

package/dist/plugin/window.js

@@ -40,6 +40,7 @@ export class WindowService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("window.state", (data) => {
             const facts = data;
             // The event carries the facts; anything else is read again.
@@ -47,7 +48,7 @@ export class WindowService {
                 this.accept(facts);
             else
                 void this.read();
-        });
+        }, "events", true);
         void this.read();
     }
     /** The palette, as the `window.state` reply carried it (`plugin.appearance`). */
@@ -91,7 +92,13 @@ export class WindowService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("window.state");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 export const windowOf = (runtime) => runtime.service("window", () => new WindowService(runtime));
@@ -101,6 +108,7 @@ export function mainWindow(scope) {
     return {
         get state() {
             service().start();
+            scope.runtime.reading("window.state");
             return service().state;
         },
         onChange(listener) {

package/dist/wire.d.ts

@@ -141,6 +141,8 @@ export interface PackageInfo {
         description: string | null;
         tags: string[];
     };
+    /** Whether it has a process now (player 0.5.18, `state: "running"`). */
+    process?: "running" | "idle";
 }
 /** Where an installed package came from (`packages.install` `source`). */
 export type WireSource = {
@@ -336,6 +338,15 @@ export interface WireRenderingState {
         reason: WireRenderingReason | null;
     };
 }
+/** `video.upscaling.state` and `video.upscaling.set` (player 0.5.16). */
+export interface WireUpscalingState {
+    available: boolean;
+    /** The same `{ code, message }` shape as a rendering reason. */
+    reason: WireRenderingReason | null;
+    enabled: boolean;
+    requested: boolean;
+    factor: number | null;
+}
 /**
  * Template arguments on the wire (`osd.show`, `osd.panel`, `dialogs.confirm`,
  * a text's `args`): data, or text values (player 0.4.3).
@@ -356,6 +367,8 @@ export interface Transport {
      */
     locale?: string;
 }
+/** The events a plugin subscribes to (`events.subscribe`). */
+type HostEvent = "source.state" | "playback.backend" | "window.state" | "packages.changed" | "bindings.changed" | "timeline.changed" | "appearance.changed" | "resolvers.fileTypes";
 export declare function createWire(transport: Transport): {
     processing: {
         state: () => Promise<import("./processing.ts").ProcessingState>;
@@ -468,6 +481,9 @@ export declare function createWire(transport: Transport): {
             state: "applied" | "waiting";
         }>;
         renderRelease: () => Promise<void>;
+        /** The GPU's video upscaler (`plugin.video.upscaling`, player 0.5.16). */
+        upscalingState: () => Promise<WireUpscalingState>;
+        upscalingSet: (enabled: boolean) => Promise<WireUpscalingState>;
     };
     /** Mark layers on the seek bar (`plugin.timeline`). */
     timeline: {
@@ -587,8 +603,19 @@ export declare function createWire(transport: Transport): {
         }) => Promise<void>;
     };
     events: {
-        /** One `events.subscribe` per name however many listeners. */
-        subscribe(event: "source.state" | "playback.backend" | "window.state" | "packages.changed" | "bindings.changed" | "timeline.changed" | "appearance.changed", listener: (data: unknown) => void): Promise<() => Promise<void>>;
+        /**
+         * One `events.subscribe` per name however many listeners. `mirror`:
+         * only the SDK keeps a copy of the state (player 0.5.18; older
+         * players ignore it); `listen` changes it.
+         */
+        subscribe(event: HostEvent, listener: (data: unknown) => void, mirror?: boolean): Promise<() => Promise<void>>;
+        /**
+         * Tell the player whether a subscribed event has a real listener
+         * (`active`) or only the SDK's copy of the state: `events.subscribe`
+         * again, which replaces the mark (player 0.5.18; older players keep
+         * one subscription per name and ignore the mark).
+         */
+        listen: (event: HostEvent, active: boolean) => Promise<void>;
     };
     ui: {
         /** Player 0.2.0: the remote images a Markdown document shows. */