@vestra-player/sdk 1.6.11 → 1.6.13

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.6.13
+
+**Who must change: plugin tests that toggle a column in fullscreen.** In fullscreen `toggle()` now only switches the column on or off (user ruling 2026-11-08); a test that asserted `effective: true` after toggling a column on in fullscreen now sees `effective: false`, `reason: "fullscreen"` (on, revealed by the right edge). Plugin code needs no change; `apiVersion` stays `vestra/1`, and the wire gains one optional field.
+
+- **`Panel.toggle` and `PanelSlot.toggle` are a switch, the same in every mode.** Compared with 1.6.11 and older, where turning a column on in fullscreen popped it out, it now only switches it on; 1.6.12's rule (a toggle on a collapsed column popped it out instead of turning it off) is withdrawn. No released player shipped 1.6.12: player 0.7.6, the first with the adjust column, is not released yet. On a column that is on, the toggle turns it off; on one that is off, it turns it on. In fullscreen "on" means the pointer at the right edge reveals the column; the toggle never pops it out (player 0.7.6), and a column switched off while it is out slides in at once. The player's own Adjust and Sidebar buttons, Toggle Sidebar and Alt+1…4 behave the same. `Panel.show` and `PanelSlot.setVisible(true)` still pop a column out in fullscreen, as documented.
+- **Wire**: `layout.set` takes an optional `reveal` (with `visible: true`, `false` switches on without popping out; absent, it reveals as before). `toggle` sends `reveal: false`; older players ignore it and pop the column out as before.
+- **`TestHost`**: `setMainWindow({ fullscreen: true })` collapses the adjust column too, `popSidebar` pops out or collapses both columns (those switched on), and `layout.set` with `reveal: false` in fullscreen leaves a column switched on but collapsed.
+
+## 1.6.12
+
+**Who must change: nobody.** Superseded by 1.6.13 for `toggle` in fullscreen: this release's rule is withdrawn, and no released player shipped it. 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/testing.d.ts

@@ -2396,8 +2396,9 @@ export declare class TestHost implements Transport {
     }>): void;
     /**
      * The pointer reached the right edge in fullscreen (`true`) or left the
-     * popped-out sidebar (`false`): the attached sidebar pops out or collapses
-     * (reference §6.3). No effect outside fullscreen, when hidden or floating.
+     * popped-out columns (`false`): the attached sidebar and the adjust column
+     * (SDK 1.6.13), those switched on, pop out or collapse (reference §6.3). No
+     * effect outside fullscreen, or on a column switched off or floating.
      *
      * @capability None.
      *

package/dist/plugin/testing.js

@@ -3005,19 +3005,22 @@ export class TestHost {
         const entering = patch.fullscreen !== undefined &&
             patch.fullscreen !== this.mainWindow.fullscreen;
         Object.assign(this.mainWindow, patch);
-        // Like the player (reference §6.3): in fullscreen the attached sidebar
-        // starts collapsed at the right edge; leaving fullscreen docks it again.
-        const sidebar = this.layout.sidebar;
-        if (entering && sidebar && sidebar.preferred && !sidebar.detached) {
-            sidebar.effective = !this.mainWindow.fullscreen;
-            sidebar.reason = this.mainWindow.fullscreen ? "fullscreen" : null;
+        // Like the player (reference §6.3): in fullscreen the attached columns
+        // (the sidebar, the adjust column) start collapsed at the right edge;
+        // leaving fullscreen docks them again.
+        for (const column of [this.layout.sidebar, this.layout.adjust]) {
+            if (entering && column && column.preferred && !column.detached) {
+                column.effective = !this.mainWindow.fullscreen;
+                column.reason = this.mainWindow.fullscreen ? "fullscreen" : null;
+            }
         }
         this.emit("window.state", this.#windowFacts());
     }
     /**
      * The pointer reached the right edge in fullscreen (`true`) or left the
-     * popped-out sidebar (`false`): the attached sidebar pops out or collapses
-     * (reference §6.3). No effect outside fullscreen, when hidden or floating.
+     * popped-out columns (`false`): the attached sidebar and the adjust column
+     * (SDK 1.6.13), those switched on, pop out or collapse (reference §6.3). No
+     * effect outside fullscreen, or on a column switched off or floating.
      *
      * @capability None.
      *
@@ -3036,11 +3039,14 @@ export class TestHost {
      * @since 1.0.0
      */
     popSidebar(popped) {
-        const sidebar = this.layout.sidebar;
-        if (!this.mainWindow.fullscreen || !sidebar?.preferred || sidebar.detached)
+        if (!this.mainWindow.fullscreen)
             return;
-        sidebar.effective = popped;
-        sidebar.reason = popped ? null : "fullscreen";
+        for (const column of [this.layout.sidebar, this.layout.adjust]) {
+            if (!column?.preferred || column.detached)
+                continue;
+            column.effective = popped;
+            column.reason = popped ? null : "fullscreen";
+        }
         this.emit("window.state", this.#windowFacts());
     }
     #windowFacts() {
@@ -4591,9 +4597,22 @@ export class TestHost {
                 state.owner = panel.owner;
             }
             if (typeof p.visible === "boolean") {
+                const out = state.preferred && state.effective;
                 state.preferred = p.visible;
-                state.effective = p.visible;
-                state.reason = p.visible ? null : "userHidden";
+                // In fullscreen a column switched on by a toggle (`reveal: false`)
+                // stays collapsed at the edge; `show()` and `setVisible` pop it out.
+                const collapsed = p.visible &&
+                    p.reveal === false &&
+                    slot !== "bottom" &&
+                    this.mainWindow.fullscreen &&
+                    !state.detached &&
+                    !out;
+                state.effective = p.visible && !collapsed;
+                state.reason = !p.visible
+                    ? "userHidden"
+                    : collapsed
+                        ? "fullscreen"
+                        : null;
                 if (this.panel?.slot === slot)
                     this.panel.visible = p.visible;
             }

package/dist/plugin/types.d.ts

@@ -2705,7 +2705,10 @@ export interface PanelSlot {
      *
      * @remarks
      * Reads the state from the player first, so it is right even without
-     * `events`.
+     * `events`. It is a switch, the same in every mode: in fullscreen a column
+     * switched on is revealed by the pointer at the right edge, and is not
+     * popped out by the toggle (SDK 1.6.13, player 0.7.6; `setVisible(true)`
+     * pops it out). Switching it off while it is out slides it in at once.
      *
      * @capability ui.mount
      *
@@ -3009,8 +3012,13 @@ export interface Panel extends View, Disposable {
      * @remarks
      * 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"
+     * position; otherwise it switches the position on at this panel's tab: a
+     * panel in a background tab comes to the front instead of the sidebar
+     * closing. It is a switch, the same in every mode, like the player's own
+     * Alt+1…4 and Adjust button: in fullscreen a column switched on is revealed
+     * by the pointer at the right edge, not popped out (SDK 1.6.13, player
+     * 0.7.6; {@link Panel.show} pops it out), and one switched off while out
+     * slides in at once. A "Show list"
      * command checked by `state.preferred && state.active` matches it. Waits
      * for {@link Panel.ready} first.
      *

package/dist/plugin/ui.js

@@ -917,10 +917,18 @@ class PanelHandle extends ViewBase {
             throw failure("invalid", "the player shows the backdrop by itself");
         await layoutOf(this.scope.runtime).read();
         const state = this.state;
+        // A switch, the same in every mode (user ruling 2026-11-08): off when
+        // on and current, else on at this tab. `reveal: false`: in fullscreen
+        // nothing pops out, the right edge reveals it (player 0.7.6; older
+        // players ignore it and pop it out).
         if (state?.preferred && state.active)
             await layoutOf(this.scope.runtime).set(this.#slot, { visible: false });
         else
-            await this.show();
+            await layoutOf(this.scope.runtime).set(this.#slot, {
+                active: this.scope.runtime.manifest.id,
+                visible: true,
+                reveal: false,
+            });
     }
     async showMenu(items, at) {
         await this.ready;
@@ -1117,7 +1125,11 @@ function slot(scope, name) {
         async toggle() {
             await service().read();
             const current = service().state[name];
-            await service().set(name, { visible: !(current?.preferred ?? true) });
+            // A switch (see Panel.toggle): nothing pops out in fullscreen.
+            await service().set(name, {
+                visible: !(current?.preferred ?? true),
+                reveal: false,
+            });
         },
         setDetached: (detached) => service().set(name, { detached }),
         activate: (plugin) => service().set(name, { active: plugin }),

package/dist/wire.d.ts

@@ -710,6 +710,13 @@ export declare function createWire(transport: Transport): {
             detached?: boolean;
             /** The plugin id of the panel whose tab becomes the current one. */
             active?: string;
+            /**
+             * With `visible: true`: `false` switches the position on without
+             * popping a column out in fullscreen (`toggle()`, SDK 1.6.13; player
+             * 0.7.6). Absent: reveal, as `show()` and `setVisible` do. Older
+             * players ignore it.
+             */
+            reveal?: boolean;
         }) => Promise<void>;
     };
     events: {

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