@vestra-player/sdk 1.5.37 → 1.5.38

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.5.38
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The marks below are read by player 0.5.18 and later; older players ignore them, and a plugin built with an older SDK keeps working (the player builds the `plugin` object with its own SDK). What may change for a plugin is the player's lazy activation, off by default in player 0.5.18 and turned on in a later release: a plugin that holds nothing only its process can serve is stopped while idle and started on its next use, so state kept only in variables is lost between uses (keep it in `plugin.storage.session`).
+
+- **Mirror subscriptions** (player 0.5.18): the SDK's own subscriptions that keep `plugin.player.state`, `plugin.window.state`, `plugin.timeline.marks`, `plugin.subtitles.state`, `plugin.appearance`, `plugin.resolvers.fileTypes` and panel positions current are sent as `events.subscribe { event, mirror: true }`. When the plugin adds a listener (an `onChange`, `onEnd`, `onFileTypesChange`) or a binding that reads that state (a command's `enabled`, `checked`, `busy` or `reason` function, a view's `bind`), the SDK sends `events.subscribe { event }` again; when the last one goes, `events.subscribe { event, mirror: true }`. A change made while the plugin activates is sent before it reports ready, so the player sees it when it classifies the plugin. The player keeps a plugin whose subscriptions are all mirrors parkable; the plugin sees no difference.
+- **`PluginInfo.process`** (player 0.5.18, optional): for a running plugin, `"running"` while its process runs, `"idle"` while the player stopped it because nothing used it (its entries stay and its next use starts it). `state` stays `"running"`, and a change of `process` alone does not fire `packages.onChange`.
+- **`TestHost.listening`**: the subscribed events the plugin really listens to (`subscriptions` without the mirrors).
+- _Plugins_ (concepts) has a new section, _Idle plugins are stopped_: what stays while a plugin is stopped, what keeps it running (listeners, bindings that read state, windows, panels, chains, streams…) and what does not (network requests, timers and promises the player does not see: as in Chrome Manifest V3, keep what they need in session storage).
+
 ## 1.5.37
 
 **Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The new API needs player 0.5.16 (`"minPlayerVersion": "0.5.16"`): older players do not load a plugin that declares the new capability `video.upscaling` (an unknown capability). A plugin that does not use it sees no difference.

package/README.md

@@ -15,6 +15,7 @@
   <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a> ·
   <a href="https://vestrasys.github.io/vestra-player-sdk/llms.txt">llms.txt</a>
 </p>
+
 ## Features
 
 - **One typed API** (`vestra/1`) for commands and menus, windows, panels, settings pages, on-screen messages, playback state and control, video and audio filters, and generated streams.

package/dist/plugin/appearance.js

@@ -29,6 +29,7 @@ class AppearanceService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("appearance.changed", (data) => {
             const event = data;
             const language = preference(event?.language);
@@ -39,7 +40,7 @@ class AppearanceService {
             const theme = event?.theme;
             if (theme && THEMES.includes(theme))
                 this.accept(theme);
-        });
+        }, "events", true);
     }
     accept(theme) {
         if (theme === this.theme)
@@ -51,7 +52,13 @@ class AppearanceService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("appearance.changed");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 const appearanceOf = (runtime) => runtime.service("appearance", () => new AppearanceService(runtime));
@@ -60,6 +67,7 @@ export function appearance(scope) {
     return {
         get theme() {
             service().start();
+            scope.runtime.reading("appearance.changed");
             return service().theme;
         },
         onChange(listener) {
@@ -80,6 +88,7 @@ export function appearance(scope) {
         },
         get language() {
             service().start();
+            scope.runtime.reading("appearance.changed");
             return service().language;
         },
         async setLanguage(language) {

package/dist/plugin/packages.js

@@ -164,6 +164,9 @@ const info = (plugin) => Object.freeze({
         ...(warning.slot === undefined ? {} : { slot: warning.slot }),
         ...(warning.owner === undefined ? {} : { owner: warning.owner }),
     }))),
+    ...(plugin.process === "running" || plugin.process === "idle"
+        ? { process: plugin.process }
+        : {}),
     ...(plugin.display
         ? {
             display: Object.freeze({

package/dist/plugin/player.js

@@ -116,7 +116,9 @@ export class PlayerService {
     output;
     constructor(runtime) {
         this.runtime = runtime;
-        runtime.on("source.state", (data) => this.accept(data));
+        // The SDK's copy of the state (a mirror): a plugin listens through
+        // `watch` and the bindings that read `state`.
+        runtime.on("source.state", (data) => this.accept(data), "events", true);
         this.output = new Latest(async ({ volume, muted }) => {
             if (volume !== undefined)
                 await runtime.host.playback.set("volume", volume);
@@ -144,9 +146,11 @@ export class PlayerService {
     }
     watch(watcher) {
         this.#watchers.add(watcher);
+        const held = this.runtime.hold("source.state");
         return {
             dispose: async () => {
                 this.#watchers.delete(watcher);
+                await held.dispose();
             },
         };
     }
@@ -429,6 +433,7 @@ export function player(scope) {
     const service = () => playerOf(scope.runtime);
     return {
         get state() {
+            scope.runtime.reading("source.state");
             return service().state;
         },
         onChange(listener) {

package/dist/plugin/resolvers.js

@@ -26,11 +26,12 @@ class FileTypesService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("resolvers.fileTypes", (data) => {
             const types = data?.fileTypes;
             if (Array.isArray(types) && types.every((t) => typeof t === "string"))
                 this.accept(types);
-        });
+        }, "events", true);
         // What changed between the start-up read and the subscription.
         const window = windowOf(this.#runtime);
         void window.read().then(() => {
@@ -50,7 +51,13 @@ class FileTypesService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("resolvers.fileTypes");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 const fileTypesOf = (runtime) => runtime.service("fileTypes", () => new FileTypesService(runtime));
@@ -58,6 +65,7 @@ export const resolvers = (scope) => ({
     get fileTypes() {
         const service = fileTypesOf(scope.runtime);
         service.start();
+        scope.runtime.reading("resolvers.fileTypes");
         return service.types;
     },
     onFileTypesChange(listener) {

package/dist/plugin/runtime.d.ts

@@ -53,15 +53,28 @@ export declare class Runtime {
     starting<T>(work: Promise<T>, report: (error: unknown) => void): Promise<T>;
     activated(): Promise<void>;
     bind(evaluate: () => void): Disposable;
+    /**
+     * A service's state for `event` is read: a binding evaluated now depends
+     * on it, so the event counts as listened to while the binding reads it.
+     */
+    reading(event: string): void;
     /** Coalesce: one evaluation pass per microtask turn, however many changes. */
     invalidate(): void;
     /**
      * 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): Disposable;
+    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): Disposable;
     /** Raw transport events the host pushes without a subscription. */
     raw(event: string, listener: Listener): Disposable;
 }

package/dist/plugin/runtime.js

@@ -87,7 +87,10 @@ export class Runtime {
     startup = new Set();
     #activating = true;
     #transport;
-    #bindings = new Set();
+    /** Each binding with the events whose state it read last time (held). */
+    #bindings = new Map();
+    /** The events read by the binding being evaluated. */
+    #reads;
     #scheduled = false;
     #events = new Map();
     views = new Map();
@@ -149,14 +152,47 @@ export class Runtime {
         this.#activating = false;
     }
     bind(evaluate) {
-        this.#bindings.add(evaluate);
+        const held = new Map();
+        this.#bindings.set(evaluate, held);
         this.invalidate();
         return {
             dispose: async () => {
+                if (this.#bindings.get(evaluate) !== held)
+                    return;
                 this.#bindings.delete(evaluate);
+                for (const hold of held.values())
+                    await hold.dispose();
+                held.clear();
             },
         };
     }
+    /**
+     * A service's state for `event` is read: a binding evaluated now depends
+     * on it, so the event counts as listened to while the binding reads it.
+     */
+    reading(event) {
+        this.#reads?.add(event);
+    }
+    /** Evaluate one binding, holding the events whose state it read. */
+    #evaluate(evaluate, held) {
+        const reads = new Set();
+        const outer = this.#reads;
+        this.#reads = reads;
+        try {
+            evaluate();
+        }
+        finally {
+            this.#reads = outer;
+            for (const [event, hold] of held)
+                if (!reads.has(event)) {
+                    held.delete(event);
+                    void hold.dispose();
+                }
+            for (const event of reads)
+                if (!held.has(event))
+                    held.set(event, this.hold(event));
+        }
+    }
     /** Coalesce: one evaluation pass per microtask turn, however many changes. */
     invalidate() {
         if (this.#scheduled)
@@ -164,9 +200,11 @@ export class Runtime {
         this.#scheduled = true;
         queueMicrotask(() => {
             this.#scheduled = false;
-            for (const evaluate of this.#bindings) {
+            for (const [evaluate, held] of [...this.#bindings]) {
+                if (this.#bindings.get(evaluate) !== held)
+                    continue;
                 try {
-                    evaluate();
+                    this.#evaluate(evaluate, held);
                 }
                 catch (error) {
                     console.error(`[${this.manifest.id}] binding failed:`, error);
@@ -177,36 +215,89 @@ export class Runtime {
     /**
      * 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") {
+    needs = "events", mirror = false) {
         let entry = this.#events.get(event);
+        const created = !entry;
         if (!entry) {
-            entry = { listeners: new Set() };
+            entry = { listeners: new Set(), active: 0 };
             this.#events.set(event, entry);
-            if (needs === null || this.can(needs)) {
-                const group = entry;
-                entry.off = this.host.events.subscribe(event, (data) => {
-                    for (const each of [...group.listeners])
-                        each(data);
-                });
-                this.starting(entry.off, (error) => console.error(`[${this.manifest.id}] subscribe ${event}:`, error));
-            }
         }
-        entry.listeners.add(listener);
         const group = entry;
+        group.listeners.add(listener);
+        if (!mirror)
+            group.active++;
+        if (created && (needs === null || this.can(needs))) {
+            group.told = group.active > 0;
+            group.off = this.host.events.subscribe(event, (data) => {
+                for (const each of [...group.listeners])
+                    each(data);
+            }, !group.told);
+            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 (group.listeners.size || this.#events.get(event) !== group)
+                if (!mirror)
+                    group.active--;
+                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) {
+        const group = this.#events.get(event);
+        if (!group)
+            return { dispose: async () => { } };
+        group.active++;
+        this.#tell(event, group);
+        let held = true;
+        return {
+            dispose: async () => {
+                if (!held)
+                    return;
+                held = false;
+                group.active--;
+                if (this.#events.get(event) === group)
+                    this.#tell(event, group);
+            },
+        };
+    }
+    /** Tell the player when `group` changes between mirror and listener. */
+    #tell(event, group) {
+        const off = group.off;
+        const active = group.active > 0;
+        if (!off || group.told === active)
+            return;
+        group.told = active;
+        // 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))
+            .catch(() => { });
+        this.starting(told, () => { });
+    }
     /** Raw transport events the host pushes without a subscription. */
     raw(event, listener) {
         const off = this.#transport.on(event, listener);

package/dist/plugin/subtitles.js

@@ -62,6 +62,8 @@ export const SUBTITLE_LIMITS = Object.freeze({
     /** Loads of every plugin in progress at the same time (8). */
     uploads: 8,
 });
+/** The events the subtitle state follows (it has none of its own). */
+const EVENTS = ["source.state", "playback.backend"];
 const raws = new WeakMap();
 const targets = new WeakMap();
 const CHUNK = 32 * 1024;
@@ -85,6 +87,7 @@ class SubtitleService {
     constructor(runtime) {
         this.#runtime = runtime;
         // No subtitle event exists: re-read when the source or backend changes.
+        // Mirrors: a plugin listens through `watch` and bindings.
         runtime.on("source.state", (data) => {
             const raw = data;
             const source = `${raw.stamp.generation}:${raw.phase}`;
@@ -92,8 +95,8 @@ class SubtitleService {
                 return;
             this.#source = source;
             void this.refresh().catch(() => { });
-        });
-        runtime.on("playback.backend", () => void this.refresh().catch(() => { }));
+        }, "events", true);
+        runtime.on("playback.backend", () => void this.refresh().catch(() => { }), "events", true);
         this.style = new Latest(async ({ style, options }) => {
             const expected = await this.expected(options);
             await this.#mutate(++this.#operation, (operationId) => runtime.host.subtitles.style({
@@ -106,12 +109,20 @@ class SubtitleService {
     }
     watch(watcher) {
         this.#watchers.add(watcher);
+        const held = EVENTS.map((event) => this.#runtime.hold(event));
         return {
             dispose: async () => {
                 this.#watchers.delete(watcher);
+                for (const hold of held.splice(0))
+                    await hold.dispose();
             },
         };
     }
+    /** A binding that reads the state follows both events. */
+    reading() {
+        for (const event of EVENTS)
+            this.#runtime.reading(event);
+    }
     /** Keep the newest view: older generations and older revisions are dropped. */
     accept(raw) {
         const old = this.raw;
@@ -258,6 +269,7 @@ export function subtitles(scope) {
     const host = () => scope.runtime.host.subtitles;
     return {
         get state() {
+            service().reading();
             return service().state;
         },
         onChange(listener) {

package/dist/plugin/testing.d.ts

@@ -535,6 +535,16 @@ export declare class TestHost implements Transport {
     readonly calls: Call[];
     /** The host events the plugin subscribed to (needs `events` etc.). */
     readonly subscriptions: Set<string>;
+    /**
+     * 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
+     */
+    readonly listening: Set<string>;
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with

package/dist/plugin/testing.js

@@ -333,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
@@ -3377,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.

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

@@ -7971,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 = {
@@ -365,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>;
@@ -599,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. */

package/dist/wire.js

@@ -255,14 +255,18 @@ export function createWire(transport) {
             set: (options) => transport.request("layout.set", options),
         },
         events: {
-            /** One `events.subscribe` per name however many listeners. */
-            async subscribe(event, listener) {
+            /**
+             * 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.
+             */
+            async subscribe(event, listener, mirror = false) {
                 const off = transport.on(event, listener);
                 let subscription = subscriptions.get(event);
                 if (!subscription) {
                     subscription = {
                         count: 0,
-                        ready: transport.request("events.subscribe", { event }),
+                        ready: transport.request("events.subscribe", mirror ? { event, mirror: true } : { event }),
                     };
                     subscriptions.set(event, subscription);
                 }
@@ -287,6 +291,13 @@ export function createWire(transport) {
                     }
                 };
             },
+            /**
+             * 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, active) => transport.request("events.subscribe", active ? { event } : { event, mirror: true }),
         },
         ui: {
             /** Player 0.2.0: the remote images a Markdown document shows. */

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.37: full reference
+# @vestra-player/sdk 1.5.38: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -329,11 +329,11 @@ The rule that follows: **state you change outside a handler, or after an `await`
 
 #### Stopping
 
-The player stops a plugin when the user disables or uninstalls it, when it is reloaded or upgraded, and when the player quits.
+The player stops a plugin when the user disables or uninstalls it, when it is reloaded or upgraded, when the player quits, and, with lazy activation, when nothing has used it for a while (Idle plugins).
 
 1. The player first removes everything the plugin owns on its side: menu items, windows, panels, settings pages, filter chains, subtitle layers, snapshots, export jobs, resolvers, generated streams.
 2. The SDK then refuses new requests, fails pending ones with `code: "disabled"` and disposes the root scope. That disposal only cleans up locally (timers, abort signals, sockets): the player-side resources are already gone.
-3. A process that has not exited 300 ms later is killed.
+3. A process that has not exited 300 ms later is killed (2 s later when it stops because it is idle).
 
 So `onDispose` cleanup must be quick and must not rely on the player. Media the plugin opened with player.open **keeps playing** after it stops.
 
@@ -344,7 +344,7 @@ A plugin's process does not live as long as the player. Within one player sessio
 - the plugin is **reloaded** (from the plugin manager, or a development load with `--plugin`) or **upgraded**;
 - it **crashed**, or failed to start, and is started again.
 
-A later player may restart a plugin in more cases: restarting plugins that share one process together when one of them faults or hangs, or stopping a plugin nobody uses and starting it on its next use. Write the plugin for those too.
+A later player may restart a plugin in more cases: restarting plugins that share one process together when one of them faults or hangs, or stopping a plugin nobody uses and starting it on its next use (Idle plugins). Write the plugin for those too.
 
 Everything in the process is gone after such a restart: variables, timers, caches, open sockets. The menus, windows and panels come back because `activate` creates them again. **Keep state that must survive a restart in session storage (or persistent storage):**
 
@@ -358,6 +358,16 @@ Session storage is for state that belongs to this run of the player: a queue the
 
 Write `activate` so that running it twice in one session is normal: read what you kept, then build the interface from it.
 
+#### Idle plugins are stopped
+
+With lazy activation (player 0.5.18 and later, while the player turns it on), the player works like a browser's extension service workers (Chrome Manifest V3): a plugin that holds nothing only its process can serve is stopped after about a minute without use, and started again by its next use.
+
+- **What stays while it is stopped**: its menu items and keys (with the last `enabled`, `checked` and `reason` it set), its settings pages, its file and link resolvers and its drop targets. Using one of them, or showing one of its settings pages, starts the plugin; it runs `activate`, registers them again, and then receives the click, the open or the drop. The player also remembers these between runs, so a plugin nobody uses is not started at launch at all.
+- **What keeps it running**: anything the player must deliver to it or that is its running work: a listener (`player.onChange`, `window.onChange`, `bindings.onChange`, `packages.onChange` and the other `onChange`, `onEnd`), a command state, panel or window binding that reads `plugin.player.state` or another state, an open window, a mounted panel, an OSD panel, a timeline layer, a filter chain, a stream or subtitle track it added, a next/previous provider, a sleep lease, a window setting, a job or snapshot in progress. Reading `plugin.player.state` inside a handler does not: the SDK reads the state again when the plugin starts.
+- **What does not keep it running**: work the player does not see. A `fetch`, a socket, a `setTimeout` or `setInterval`, or a promise the plugin awaits is lost when an idle plugin is stopped, as in Chrome. Set the command's `busy` while its work runs (a busy command keeps the plugin running), or keep what it needs in session storage and pick it up in `activate`.
+
+`TestHost.listening` lists the events a plugin really listens to; empty means listeners do not keep it running.
+
 #### The data directory
 
 plugin.dataDirectory is a writable directory for the plugin's own files (settings, caches, remembered folders). It needs no capability; the player creates it before it starts the plugin.
@@ -10735,6 +10745,10 @@ interface PluginInfo {
    * The manifest's display texts in the interface language, translated with that package's catalog; absent from players before 0.4.3 (read `manifest.json` there).
    */
   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 Packages.onChange.
+   */
+  process?: "running" | "idle";
 }
 ```
 
@@ -12796,6 +12810,10 @@ class TestHost implements Transport {
   readonly calls: Call[];
   /** The host events the plugin subscribed to (needs `events` etc.). */
   readonly subscriptions: Set<string>;
+  /**
+   * 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…).
+   */
+  readonly listening: Set<string>;
   /**
    * The player's source facts (phase, position, duration, paused, rate, audio tracks, loop, ...). Wire-level shape; change it with TestHost.setSource, which also broadcasts it.
    */

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.37: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
+> @vestra-player/sdk 1.5.38: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
 
 **Rules**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2636–2706.
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2646–2716.
 
 **main.ts**
 
@@ -78,9 +78,9 @@ export default async function activate(plugin: Plugin) {
 - `secrets`: Secrets.get/set/delete
 - `rendering.manage`: Rendering.setPreference/restartPlayer
 - `video.upscaling`: VideoUpscaling.state/set
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2707–2767.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2717–2777.
 
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L2077–2265; TestHost: L12744.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L2087–2275; TestHost: L12758.
 
 **Command line**
 
@@ -108,39 +108,39 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player
-- Others: PluginError, llms-full.txt L3770.
+- Others: PluginError, llms-full.txt L3780.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; pages: [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–237
-- Concepts: How a plugin runs L238–408; Commands, menus and key bindings L409–520; Playback state, controls and sources L521–666; Video and audio processing L667–753; Windows, panels, settings pages, dialogs and the OSD L754–1042
-- How-to: Control playback L1043–1171; Store a plugin's data L1172–1239; Load subtitles from a plugin L1240–1318; Keep a slider responsive while dragging L1319–1493; Remember a window's state between runs L1494–1623; Offer a GPU rendering switch L1624–1744; Translate a plugin L1745–1928; Migrate a plugin to English source text L1929–2076; Test a plugin L2077–2265; Publish a plugin L2266–2354; Migrating off package rollback (1.5.16, removed in 1.5.17) L2355–2430
-- Guidelines: Interface guidelines L2431–2538; Menu guidelines L2539–2635
-- Reference: Manifest L2636–2706; Capabilities L2707–2767; Limits L2768–2897; Commands, menus and bindings L2898–3381; Platforms L3382–3412; Theme L3413–3634; Command line L3635–3692
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3693–12428
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12429–15144
+- Concepts: How a plugin runs L238–418; Commands, menus and key bindings L419–530; Playback state, controls and sources L531–676; Video and audio processing L677–763; Windows, panels, settings pages, dialogs and the OSD L764–1052
+- How-to: Control playback L1053–1181; Store a plugin's data L1182–1249; Load subtitles from a plugin L1250–1328; Keep a slider responsive while dragging L1329–1503; Remember a window's state between runs L1504–1633; Offer a GPU rendering switch L1634–1754; Translate a plugin L1755–1938; Migrate a plugin to English source text L1939–2086; Test a plugin L2087–2275; Publish a plugin L2276–2364; Migrating off package rollback (1.5.16, removed in 1.5.17) L2365–2440
+- Guidelines: Interface guidelines L2441–2548; Menu guidelines L2549–2645
+- Reference: Manifest L2646–2716; Capabilities L2717–2777; Limits L2778–2907; Commands, menus and bindings L2908–3391; Platforms L3392–3422; Theme L3423–3644; Command line L3645–3702
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3703–12442
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12443–15162
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L4096, Scope L3845, PluginError L3770, Disposable L3708
-- Commands L4493; Windows L5430; Panels L6876; Dialogs L7544; Player L8285; video: VideoFilter L9165, VideoView L9265, RenderOptions L9352, VideoUpscaling L9548; audio: AudioFilter L9210; Subtitles L9744; media: MediaCapture L10148; Resolvers L10378; Packages L10776; Osd L9030; Host L8872; Clipboard L11104; Power L11191; Tools L11250; Storage L11402; System L11601; Secrets L11681; window: MainWindow L7193; App L7373; Rendering L11944; Bindings L11004; Ui L4782; Timeline L7105; Drops L6123; Appearance L6204; I18n L6437; Settings L6720.
+- Plugin L4106, Scope L3855, PluginError L3780, Disposable L3718
+- Commands L4503; Windows L5440; Panels L6886; Dialogs L7554; Player L8295; video: VideoFilter L9175, VideoView L9275, RenderOptions L9362, VideoUpscaling L9558; audio: AudioFilter L9220; Subtitles L9754; media: MediaCapture L10158; Resolvers L10388; Packages L10790; Osd L9040; Host L8882; Clipboard L11118; Power L11205; Tools L11264; Storage L11416; System L11615; Secrets L11695; window: MainWindow L7203; App L7383; Rendering L11958; Bindings L11018; Ui L4792; Timeline L7115; Drops L6133; Appearance L6214; I18n L6447; Settings L6730.
 
 ## Examples
 
 Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L15579–15668
-- blur: A tool window with one slider that blurs the playing video. L15669–15930
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L15931–16263
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L16264–16450
-- panel-menu: A sidebar panel with its own right-click menu. L16451–16659
-- menus: Radio menu items, separator groups and a menu item whose title changes. L16660–16819
-- theme-widgets: A tool window drawn with the player's theme and widgets. L16820–16983
-- markdown: A window that shows a Markdown document. L16984–17180
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L17181–17348
+- hello: The README Quick start: one menu command and an on-screen message. L15597–15686
+- blur: A tool window with one slider that blurs the playing video. L15687–15948
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L15949–16281
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L16282–16468
+- panel-menu: A sidebar panel with its own right-click menu. L16469–16677
+- menus: Radio menu items, separator groups and a menu item whose title changes. L16678–16837
+- theme-widgets: A tool window drawn with the player's theme and widgets. L16838–17001
+- markdown: A window that shows a Markdown document. L17002–17198
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L17199–17366
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.37",
+  "version": "1.5.38",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {