@vestra-player/sdk 1.5.55 → 1.5.57

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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

@@ -3140,7 +3140,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 +8430,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.
@@ -9721,7 +9731,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.57: 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.57",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {