@vestra-player/sdk 1.5.55 → 1.5.58

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.5.58
+
+**Who must change: nobody.** Documentation only: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability, no player version needed. Plugin authors should read what the player's new plugin supervisor does with their plugin (player 0.6.6, and the defaults planned for 0.6.7), and check that `activate` never waits for its own commands or views.
+
+- **The plugin supervisor, as a plugin sees it** ([How the player runs and talks to plugins](docs/explanation/host-and-node.md), [How a plugin runs](docs/explanation/plugins.md)). Player 0.6.6: a failed start is tried up to three more times; a built-in that crashes starts again by itself after 3 s, 6 s…; the fifth crash within 10 minutes stops a plugin until it is reloaded; an own process's JavaScript heap is capped at 512 MB (V8's heap only, not `Buffer` contents or addons), and passing it ends the process with "<name> ran out of memory"; a process that ended by itself gets no `runtime.stop`; without on-demand start a third-party plugin is listed as failed on its first crash, as before; at quit every plugin is stopped at once with 1 s in all; and two processes of one plugin never use its data directory at the same time. With on-demand start (lazy activation, `VESTRA_LAZY=1` in 0.6.6): a crashed plugin keeps its entries, shown disabled with the reason during a pause of 1 s, 2 s, 4 s…, and starts again on its next use (a resident plugin by itself); third-party plugins start a few at a time, clicks first; every start holds its clicks, resolutions, drops and view callbacks until `runtime.ready` (so an `activate` that awaits its own command or view callback waits until the start timeout); at most 64 are held per plugin, and one that cannot be taken is answered ("<name> is busy", "… could not start", "… is disabled") instead of dropped; busy work (a `busy` command, a dialog, a settings page shown, a resolution) keeps a plugin running with no time limit, and its idle time counts from when the work ends. Planned for player 0.6.7: on-demand start for everyone; a process budget for the machine's memory and the system's memory pressure put idle plugins in standby early, with the stop reason `idle`; idle time 30 s, start timeout 60 s, 5 s grace for a disable, uninstall, reload, upgrade or standby, a 5-minute cap on a player request awaiting the plugin's reply (a resolution; declared busy work stays uncapped), and a resident plugin never goes to standby. The source excerpts of host code that no longer exists (the lazy-activation trigger list, the 15-second activation record, the 250 ms idle poll, the stop's 5 ms poll) are replaced by descriptions of the current behaviour.
+- **[Reference: limits › Plugin processes](docs/reference/limits.md#plugin-processes)**: heap cap, start timeout, retries, start limit, restart pauses, stop graces, quit, idle time, request timeout, start slots (`min(4, max(2, cores / 2))` plus a reserve for clicks), held triggers (64), waiting starts (256), the process budget (`clamp(physical MiB / 2 × 0.30 / 85, 3, 16)`) and the memory pressure thresholds (both planned for 0.6.7), for player 0.6.6 and as planned for 0.6.7.
+- **`StopReason`** lists when each reason comes with the supervisor: `quit` also after a lost GPU device, `disable` clears session storage, `idle` also for the process budget and memory pressure (planned for 0.6.7; never for a busy plugin), `failed` also for a start timeout (possibly while `activate` runs) and, planned for 0.6.7, an unanswered request; a crash or running out of memory is no stop at all. The stop reasons are no longer described as planned: they shipped in player 0.6.4. **`PluginInfo.process`** `"idle"` also covers the pause after a crash before a plugin starts again. `Plugin`, `DisposeInfo` and [Store a plugin's data](docs/how-to/store-data.md) give the new stop graces.
+- **`appearance.changed` says what changed** (player 0.6.6): `"changed": ["theme"]` or `["language"]` beside `theme` and `language`. This SDK does not read it yet; a later release uses it so that a plugin woken by a language change no longer hears its unchanged theme once.
+
+## 1.5.57
+
+**Who must change: nobody.** The first npm release with 1.5.56's fix: no change to the TypeScript API or the wire, `apiVersion` stays `vestra/1`, no new capability, no player version needed.
+
+- **1.5.56 never reached npm.** Its tag was pushed, but the release run (41502365359) skipped `publish` because GitHub never gave its two macOS jobs a hosted runner (capacity) and they were cancelled. 1.5.57 publishes the same code: `appearance.onChange` and `resolvers.onFileTypesChange` hear a change the player woke the plugin for, and the session-storage clearing docs, as described under [1.5.56](#1556). Install 1.5.57; there is no `@vestra-player/sdk@1.5.56` on npm.
+- _Release process_: runner capacity no longer blocks a release (product-owner ruling, 2026-11-02). `release.yml` publishes once `verify`, `static`, `build`, `docs` and the Ubuntu and Windows tests and examples pass; macOS tests and examples still run on every release as `test-macos`, beside `publish` and without gating it. `_test.yml` takes an `os` input (a JSON array of runner labels, all three by default), so pull requests and `main` still test and gate on Ubuntu, Windows and macOS as before. [Maintaining › Releasing](docs/maintaining.md#releasing) says so.
+
+## 1.5.56
+
+**Who must change: nobody.** A fix: no change to the TypeScript API or the wire, `apiVersion` stays `vestra/1`, no new capability, no player version needed.
+
+- **`appearance.onChange` and `resolvers.onFileTypesChange` hear a change the player woke the plugin for.** A plugin the player stopped and starts again to deliver a palette or file-type change ([Idle plugins are stopped](docs/explanation/plugins.md#idle-plugins-are-stopped)) read the new value with `window.state` at start; the held `appearance.changed` or `resolvers.fileTypes` that followed compared equal to it, so the listeners never ran. The SDK now compares an event with what the listeners last heard, not with the value read at start: they hear the change once, and the same value again is still not a change. The player sends `resolvers.fileTypes` only when the list changed. It sends `appearance.changed` when the theme or the language changed, both values each time; an event whose language differs from the last one the SDK saw is a language change, and as before does not call `onChange` unless the theme differs too (also for the echo of the plugin's own `setLanguage`). One case remains: a plugin the player woke for a language change alone cannot tell it from a theme change, since the event does not say what changed, and its `onChange` may hear the unchanged theme once. A field naming the change could be added to the event later without breaking anything. `appearance.theme`, `resolvers.fileTypes` and views read the same values as before. `packages.onChange` and `bindings.onChange` (the other two events that wake a plugin) never compared, and are unchanged.
+- _Docs_: when session storage is cleared, corrected against the player: also when a store or another plugin with `plugins.manage` disables the plugin (`packages.setEnabled(id, false)`, or an update installed with `enabled: false`, player 0.6.4), and when an earlier installation kept for a later reinstall (after a `replace`) is dropped because the player keeps only so many; [How a plugin runs › Stopping](docs/explanation/plugins.md#stopping) names other plugins with `plugins.manage` too. `SessionStorage`, [How a plugin runs › Restarts](docs/explanation/plugins.md#restarts-activate-can-run-more-than-once) and [Store a plugin's data](docs/how-to/store-data.md) say so. `Appearance.onChange` and `Resolvers.onFileTypesChange` describe the wake.
+
 ## 1.5.55
 
 **Who must change: nobody, but check `TestHost` tests that update a disabled plugin.** Additive: `InstallOptions` gains `enabled` and `TestHost` gains `installKeepsDisabled`, `apiVersion` stays `vestra/1`, no new capability, and existing code still compiles. Older players ignore the option, and an install there always enables the plugin. One `TestHost` behaviour change at run time: like player 0.6.4, it now keeps a `disabled` entry disabled when the plugin under test installs an update or reinstall over it without `enabled`, where it used to make it `running`. A test that expects the update to run (the player's Store test did) sets `host.installKeepsDisabled = false` to keep playing players up to 0.6.3, or asserts the new rule; a test that covers both runs once with each.

package/dist/plugin/appearance.js

@@ -18,12 +18,34 @@ class AppearanceService {
     /** The saved interface language (the next start's). */
     language;
     #listeners = new Set();
+    /**
+     * The theme listeners last heard (or the last event's), not the one read
+     * at start: a plugin woken from standby reads the new theme from
+     * `window.state`, then gets the `appearance.changed` the player held for
+     * it, and its listeners still hear that change. Left unset until the
+     * first event on purpose: set from the start-up read, it would hide that
+     * held change again.
+     */
+    #notified;
+    /**
+     * The language as the start-up read and later events carried it (not
+     * `language`, which the plugin's own `setLanguage` changes before its
+     * echo arrives). The player sends `appearance.changed` once per change
+     * of the theme or of the language, each with both values: an event whose
+     * language differs from this one is a language change, and its theme is
+     * compared with `theme` as before. Only a newest event that repeats the
+     * start-up language is taken for a theme change; a plugin woken for a
+     * language change gets that too, so its listeners may hear the unchanged
+     * theme once (the event does not say what changed).
+     */
+    #eventLanguage;
     #started = false;
     constructor(runtime) {
         this.#runtime = runtime;
         this.theme =
             windowOf(runtime).appearance ?? "vestra";
         this.language = preference(windowOf(runtime).language) ?? "system";
+        this.#eventLanguage = this.language;
     }
     start() {
         if (this.#started)
@@ -33,22 +55,47 @@ class AppearanceService {
         this.#runtime.on("appearance.changed", (data) => {
             const event = data;
             const language = preference(event?.language);
+            // Older players send no language: their events are theme changes.
+            const languageChanged = language !== undefined && language !== this.#eventLanguage;
+            if (language)
+                this.#eventLanguage = language;
             if (language && language !== this.language) {
                 this.language = language;
                 this.#runtime.invalidate();
             }
             const theme = event?.theme;
-            if (theme && THEMES.includes(theme))
+            if (!theme || !THEMES.includes(theme))
+                return;
+            if (languageChanged) {
+                // The theme came along unchanged (or this plugin set it already).
                 this.accept(theme);
+                this.#notified = theme;
+            }
+            else
+                this.changed(theme);
         }, "events", true);
     }
+    /** A theme change event: listeners hear it unless they already did. */
+    changed(theme) {
+        const changed = theme !== this.theme;
+        this.theme = theme;
+        if (theme !== this.#notified)
+            this.#notify(theme);
+        if (changed)
+            this.#runtime.invalidate();
+    }
+    /** After this plugin's own `set`: only a change from the current theme. */
     accept(theme) {
         if (theme === this.theme)
             return;
         this.theme = theme;
+        this.#notify(theme);
+        this.#runtime.invalidate();
+    }
+    #notify(theme) {
+        this.#notified = theme;
         for (const listener of [...this.#listeners])
             listener(theme);
-        this.#runtime.invalidate();
     }
     watch(listener) {
         this.#listeners.add(listener);

package/dist/plugin/resolvers.js

@@ -17,6 +17,14 @@ class FileTypesService {
     #runtime;
     types;
     #listeners = new Set();
+    /**
+     * The list listeners last heard, not the one read at start: a plugin
+     * woken from standby reads the new list from `window.state`, then gets
+     * the `resolvers.fileTypes` the player held for it, and its listeners
+     * still hear that change. The player sends the event only when the list
+     * changed, so a first event is always news to the listeners.
+     */
+    #notified;
     #started = false;
     constructor(runtime) {
         this.#runtime = runtime;
@@ -30,7 +38,7 @@ class FileTypesService {
         this.#runtime.on("resolvers.fileTypes", (data) => {
             const types = data?.fileTypes;
             if (Array.isArray(types) && types.every((t) => typeof t === "string"))
-                this.accept(types);
+                this.changed(types);
         }, "events", true);
         // What changed between the start-up read and the subscription.
         const window = windowOf(this.#runtime);
@@ -39,16 +47,33 @@ class FileTypesService {
                 this.accept(window.fileTypes, this.#runtime.can("events"));
         });
     }
-    /** `notify`: false without `events`, whose listeners never fire. */
+    /** From `resolvers.fileTypes`: listeners hear it unless they already did. */
+    changed(types) {
+        const changed = !sameTypes(types, this.types);
+        if (changed)
+            this.types = Object.freeze([...types]);
+        if (!this.#notified || !sameTypes(types, this.#notified))
+            this.#notify(types);
+        if (changed)
+            this.#runtime.invalidate();
+    }
+    /**
+     * From a `window.state` read: only a change from the current list.
+     * `notify`: false without `events`, whose listeners never fire.
+     */
     accept(types, notify = true) {
         if (sameTypes(types, this.types))
             return;
         this.types = Object.freeze([...types]);
         if (notify)
-            for (const listener of [...this.#listeners])
-                listener([...types]);
+            this.#notify(types);
         this.#runtime.invalidate();
     }
+    #notify(types) {
+        this.#notified = Object.freeze([...types]);
+        for (const listener of [...this.#listeners])
+            listener([...types]);
+    }
     watch(listener) {
         this.#listeners.add(listener);
         const held = this.#runtime.hold("resolvers.fileTypes");

package/dist/plugin/types.d.ts

@@ -524,8 +524,10 @@ export interface Scope extends Disposable {
  * (menus, windows, panels, filters, subtitle layers, snapshots, jobs,
  * resolvers, streams); pending requests then fail with `disabled` and the
  * root scope is disposed for local cleanup (timers, signals, sockets). A
- * process that has not exited after 300 ms is killed. Media the plugin
- * opened with {@link Player.open} keeps playing.
+ * process that has not exited after its grace is killed: 300 ms in player
+ * 0.6.6 (2 s when it goes to standby), planned to be 5 s from player 0.6.7
+ * (300 ms after a fault); at quit all plugins together get 1 s. Media the
+ * plugin opened with {@link Player.open} keeps playing.
  *
  * @example Write a minimal plugin with one menu item
  * Tools ▸ Say hello, or Ctrl+H, shows "Hello from" and the plugin's id.
@@ -575,8 +577,8 @@ export interface Plugin extends Scope {
      */
     readonly dataDirectory: string;
     /**
-     * Why the player stops this plugin (SDK 1.5.54; the reasons are planned
-     * for player 0.6.4): set when the stop begins, before any
+     * Why the player stops this plugin (SDK 1.5.54, player 0.6.4): set when
+     * the stop begins, before any
      * {@link Scope.onDispose} cleanup runs. `undefined` while the plugin
      * runs, and for every stop by an older player (one whose own SDK is older
      * than 1.5.54 does not have the property at all). See {@link StopReason}.
@@ -587,23 +589,40 @@ export interface Plugin extends Scope {
  * Why the player stopped the plugin ({@link DisposeInfo.reason},
  * {@link Plugin.stopReason}).
  *
- * - `quit`: the player quits.
- * - `disable`: the user disabled the plugin.
+ * - `quit`: the player quits (or restarts after a lost GPU device). Every
+ *   plugin is stopped at the same time, with 1 s in all (300 ms after a
+ *   lost device; player 0.6.6).
+ * - `disable`: the user, or a plugin with `plugins.manage`, switched the
+ *   plugin off. Its session storage is cleared.
  * - `uninstall`: the user uninstalls it.
  * - `reload`: it is reloaded (from the plugin manager, or a development
  *   load with `--plugin`).
  * - `upgrade`: an install or update replaces the running version; also a
  *   new version stopped because its install was cancelled (the previous
  *   version comes back).
- * - `idle`: lazy activation parks it; its next use starts it again
+ * - `idle`: the plugin goes to standby and its next use starts it again;
+ *   its menu items, keys, settings pages, resolvers and drop targets stay,
+ *   and so does its session storage
  *   ([Idle plugins](../../docs/explanation/plugins.md#idle-plugins-are-stopped)).
- *   Lazy activation is off by default (`VESTRA_LAZY=1` turns it on); when
- *   on, it parks a plugin after a while without use, and parks one whose
- *   first run it judges lazy right after it is ready.
+ *   Only with on-demand start (lazy activation), off by default up to
+ *   player 0.6.6 (`VESTRA_LAZY=1` turns it on) and planned for everyone in
+ *   player 0.6.7. It comes after the idle time without use (60 s; 30 s
+ *   planned for 0.6.7), right after a first run that holds nothing live,
+ *   and when the player's limit on third-party processes or low system
+ *   memory puts an idle plugin in standby early (planned for 0.6.7). A busy
+ *   plugin never gets it; a resident one (it held something live when it
+ *   became ready) only after the idle time, and from player 0.6.7 (planned)
+ *   never.
  * - `failed`: the player stops it for a fault it can still tell the plugin
- *   about (planned to cover a malformed request, an unreadable or
- *   oversized line, an activation timeout, an uncaught exception the
- *   shared process attributes to this plugin).
+ *   about: a malformed request, an unreadable or oversized line, a start
+ *   that is not ready within the start timeout (15 s; 60 s planned for
+ *   player 0.6.7; the stop may come while `activate` still runs), an
+ *   uncaught exception the shared process attributes to this plugin, and,
+ *   planned for player 0.6.7, a request from the player (a resolution) it
+ *   leaves unanswered for 5 minutes. From player 0.6.6 the player may
+ *   start it again afterwards (a built-in or resident plugin by itself, a
+ *   plugin with on-demand start on its next use), until the fifth fault
+ *   within 10 minutes.
  * - `host-lost`: the plugin's runner saw its pipe to the player close
  *   without a stop: the player crashed or was killed. Requests are refused
  *   with `disabled`; clean up locally only. Player 0.6.4 sends `quit` on a
@@ -614,20 +633,22 @@ export interface Plugin extends Scope {
  * {@link Scope.onDispose} cleanups do not run. That is the case when its
  * own process is killed because its input queue is full or a write to it
  * failed, when its own process fails to activate (the runner exits without
- * cleaning up), when the process has already exited, and when the shared
- * runner is restarted as a whole (a hang, a fault it cannot attribute, an
- * unreadable line of its own, a member's full input queue, the runner
- * exiting): every member is killed with it. Keep state that must survive
- * such an end in storage as it changes, not only in a cleanup.
- *
- * Planned for player 0.6.4: the player sends the reason with
- * `runtime.stop` and its runner reports `host-lost`; the exact list may
- * still change with that release. Players up to 0.6.3 give no reason for
- * any stop, a lost player included (`undefined`); so does a stop that
- * does not come from the player (a `TestHost` `stop()` without a reason).
- * A value this SDK does not know reads as `undefined`.
- *
- * @player 0.6.4 (planned); older players give no reason (`undefined`).
+ * cleaning up), when the process ended by itself (it crashed, or its
+ * JavaScript heap passed the 512 MB cap of player 0.6.6 and V8 ended it:
+ * "ran out of memory"), and when the shared runner is restarted as a whole
+ * (a hang, a fault it cannot attribute, an unreadable line of its own, a
+ * member's full input queue, the runner exiting): every member is killed
+ * with it. Keep state that must survive such an end in storage as it
+ * changes, not only in a cleanup. Timings and restarts are in
+ * [How the player runs and talks to plugins](../../docs/explanation/host-and-node.md#crashes-and-restarts).
+ *
+ * Player 0.6.4 and later send the reason with `runtime.stop`, and their
+ * runner reports `host-lost`. Players up to 0.6.3 give no reason for any
+ * stop, a lost player included (`undefined`); so does a stop that does not
+ * come from the player (a `TestHost` `stop()` without a reason). A value
+ * this SDK does not know reads as `undefined`.
+ *
+ * @player 0.6.4; older players give no reason (`undefined`).
  * @since 1.5.54
  * @category Plugin
  */
@@ -647,8 +668,9 @@ export interface DisposeInfo {
      */
     readonly stopping: boolean;
     /**
-     * Why the player stops the plugin (planned for player 0.6.4); `undefined` while
-     * `stopping` is false, and for every stop by an older player.
+     * Why the player stops the plugin (player 0.6.4; the causes are listed at
+     * {@link StopReason}); `undefined` while `stopping` is false, and for
+     * every stop by an older player.
      */
     readonly reason?: StopReason;
 }
@@ -3140,7 +3162,13 @@ export interface Appearance {
      * Needs `events`: without it the listener never runs for other plugins'
      * changes. Views need no help to follow the palette; use this for things
      * the plugin draws itself (a rendered image, colours it computes). Errors
-     * go to {@link Scope.onError}.
+     * go to {@link Scope.onError}. When the player starts a stopped plugin
+     * for a palette change (player 0.5.21), {@link Appearance.theme} already
+     * has the new palette at start and the listener still hears the change
+     * (SDK 1.5.56; before, it did not run). A language change does not call
+     * it, except in one case: a plugin started for a language change alone
+     * may hear the unchanged palette once, since the player's event does not
+     * say which of the two changed.
      *
      * @capability events
      *
@@ -8424,6 +8452,10 @@ export interface Resolvers {
     /**
      * {@link Resolvers.fileTypes} changed: a file resolver was added, or its
      * plugin stopped. Needs `events`; without it the listener never fires.
+     * When the player starts a stopped plugin for this change (player
+     * 0.5.21), {@link Resolvers.fileTypes} already has the new list at start
+     * and the listener still hears the change (SDK 1.5.56; before, it did not
+     * run).
      *
      * @param listener - Receives the new list.
      * @returns A handle that removes the listener.
@@ -8803,11 +8835,19 @@ export interface PluginInfo {
     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}.
+     * while the plugin is switched on but has no process. That is standby
+     * with on-demand start (lazy activation): nothing used it for the idle
+     * time, or the player's limit on third-party processes or low system
+     * memory stopped it early (planned for player 0.6.7); it starts again on its next
+     * use, and its menu items, keys, settings pages, resolvers and drop
+     * targets stay. From player 0.6.6 it is also the pause after a crash: a
+     * built-in or resident plugin waiting to start again by itself, or a
+     * plugin with on-demand start whose commands are shown disabled with the
+     * reason until the pause ends. Absent in other states and from players
+     * before 0.5.18. A change between the two alone does not fire
+     * {@link Packages.onChange}; a plugin stopped by the start limit (five
+     * crashes within 10 minutes) is `state: "failed"` with that in
+     * {@link PluginInfo.error}.
      *
      * @since 1.5.38
      */
@@ -9721,7 +9761,10 @@ export interface Storage {
  * | --- | --- |
  * | The plugin's process restarts: reload, upgrade, crash | kept |
  * | The plugin failed to start or failed, and starts again | kept |
- * | The user disables the plugin, or uninstalls it | cleared |
+ * | The user, or a plugin with `plugins.manage` (`packages.setEnabled(id, false)`), disables the plugin | cleared |
+ * | An update or reinstall with `enabled: false` switches an enabled plugin off (player 0.6.4) | cleared |
+ * | The plugin is uninstalled | cleared |
+ * | An earlier installation kept for a later reinstall (after a `replace`) is dropped because the player keeps only so many | cleared |
  * | The player quits | cleared |
  *
  * - **Per plugin.** A plugin sees only its own keys. Like

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.55: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
+> @vestra-player/sdk 1.5.58: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
 
 ## Read the documentation
 

package/package.json

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