@vestra-player/sdk 1.6.11 → 1.6.12

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.6.12
+
+**Who must change: nobody.** A behaviour fix of `toggle` in fullscreen, an example fix and a development warning; no new API, `apiVersion` stays `vestra/1`.
+
+- **`Panel.toggle` and `PanelSlot.toggle` slide a collapsed column out.** In fullscreen a sidebar or adjust column the user wants shown is collapsed at the right edge (`reason: "fullscreen"`). Toggling it then turned it off; it now shows it, which player 0.7.6 answers by sliding the column out, as its own Adjust button and Alt+1…4 do. Toggling a column that is on screen still turns it off. With players before 0.7.6 a show of a collapsed column changes nothing on screen, as before.
+- **[adjust-panel](docs/examples/adjust-panel.md)** declares `events`: without it `plugin.player.state` changes only after the plugin's own calls, so a panel activated before a file was opened stayed disabled at 1×. A new test opens the file after activation. Its presets are four (0.5×, 1×, 1.5×, 2×), which fit the adjust column at its least width. No other example reads `player.state` without `events`.
+- **A development warning for state followed without `events`.** A plugin that registers an `onChange` or a `bind` whose function reads changing state (`player.state`, a panel position, and the like) without the `events` capability gets one line in its log, once per plugin: changes made elsewhere never reach it. Only a warning; behaviour is unchanged. `TestHost` already behaved like the player here (it delivers `source.state` and the other state events only to a plugin that subscribed, which needs `events`): a new test pins that down. The example's old tests passed because they opened the file before starting the plugin or did not check `enabled`. No SDK example or test relied on the opposite, so nobody must change.
 ## 1.6.11
 
 **Who must change: nobody.** Additions only: a mount slot, a panel position, a button icon and `TestHost` support; `apiVersion` stays `vestra/1`, no new capability. A plugin that mounts `"adjust"` sets `minPlayerVersion` to `0.7.6`: older players refuse the slot (`invalid`), which fails the activation like any refused mount.

package/dist/plugin/runtime.js

@@ -208,6 +208,8 @@ export class Runtime {
     /** The plugin was disposed: no safety pass is armed any more. */
     #stopped = false;
     #events = new Map();
+    /** The missing `events` warning was given (once per plugin). */
+    #warnedEvents = false;
     views = new Map();
     commands = new Map();
     services = new Map();
@@ -617,6 +619,10 @@ export class Runtime {
             group.active++;
             group.whys.set(token, listenerWhy(this.callSite()));
         }
+        if (created && needs === "events" && !this.can(needs))
+            group.unheard = true;
+        if (!mirror && group.unheard)
+            this.#warnUnheard(event);
         if (created && (needs === null || this.can(needs))) {
             group.told = group.active > 0;
             const whys = group.told ? allWhys(group) : undefined;
@@ -658,6 +664,8 @@ export class Runtime {
         const group = this.#events.get(event);
         if (!group)
             return { dispose: async () => { } };
+        if (group.unheard)
+            this.#warnUnheard(event);
         group.active++;
         const token = {};
         group.whys.set(token, why ?? listenerWhy(this.callSite()));
@@ -675,6 +683,19 @@ export class Runtime {
             },
         };
     }
+    /**
+     * A development warning, once per plugin, no behaviour change (SDK
+     * 1.6.12): the plugin follows `event` (an `onChange`, a `bind` that reads
+     * the state) without the `events` capability, so changes made elsewhere
+     * (the user, the player, another plugin) never reach it; the state moves
+     * only after its own calls.
+     */
+    #warnUnheard(event) {
+        if (this.#warnedEvents)
+            return;
+        this.#warnedEvents = true;
+        console.warn(`[${this.manifest.id}] follows ${event} (onChange, or a bind() that reads the state) without the "events" capability: changes made elsewhere will not reach it, only its own calls refresh the state. Declare "events" in manifest.json.`);
+    }
     /**
      * Tell the player when `group` changes between mirror and listener, and
      * why it listens when that changed.

package/dist/plugin/types.d.ts

@@ -2705,7 +2705,9 @@ export interface PanelSlot {
      *
      * @remarks
      * Reads the state from the player first, so it is right even without
-     * `events`.
+     * `events`. A sidebar or adjust column wanted shown but collapsed at the
+     * right edge of fullscreen (`reason: "fullscreen"`) slides out instead of
+     * being turned off (SDK 1.6.12; player 0.7.6 pops it out).
      *
      * @capability ui.mount
      *
@@ -3010,7 +3012,10 @@ export interface Panel extends View, Disposable {
      * Reads the state from the player first. When the position is shown
      * (`preferred`) and this panel's tab is the current one, it hides the
      * position; otherwise it does {@link Panel.show}: a panel in a background
-     * tab comes to the front instead of the sidebar closing. A "Show list"
+     * tab comes to the front instead of the sidebar closing, and a column
+     * collapsed at the right edge of fullscreen (`reason: "fullscreen"`) slides
+     * out instead of being turned off (SDK 1.6.12; player 0.7.6 pops it out),
+     * like the player's own Alt+1…4 and Adjust button. A "Show list"
      * command checked by `state.preferred && state.active` matches it. Waits
      * for {@link Panel.ready} first.
      *

package/dist/plugin/ui.js

@@ -917,7 +917,9 @@ class PanelHandle extends ViewBase {
             throw failure("invalid", "the player shows the backdrop by itself");
         await layoutOf(this.scope.runtime).read();
         const state = this.state;
-        if (state?.preferred && state.active)
+        // Collapsed at the edge of fullscreen (wanted shown, not on screen):
+        // slide it out rather than turn it off (player 0.7.6 pops it out).
+        if (state?.preferred && state.active && state.reason !== "fullscreen")
             await layoutOf(this.scope.runtime).set(this.#slot, { visible: false });
         else
             await this.show();
@@ -1117,7 +1119,11 @@ function slot(scope, name) {
         async toggle() {
             await service().read();
             const current = service().state[name];
-            await service().set(name, { visible: !(current?.preferred ?? true) });
+            // Collapsed at the edge of fullscreen: slide it out (see Panel.toggle).
+            const collapsed = current?.reason === "fullscreen";
+            await service().set(name, {
+                visible: collapsed || !(current?.preferred ?? true),
+            });
         },
         setDetached: (detached) => service().set(name, { detached }),
         activate: (plugin) => service().set(name, { active: plugin }),

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.6.11: 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.6.12: 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.6.11",
+  "version": "1.6.12",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {