@vestra-player/sdk 1.6.12 → 1.6.13

package/CHANGELOG.md

@@ -1,8 +1,16 @@
 # 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.** A behaviour fix of `toggle` in fullscreen, an example fix and a development warning; no new API, `apiVersion` stays `vestra/1`.
+**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`.

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,9 +2705,10 @@ export interface PanelSlot {
      *
      * @remarks
      * Reads the state from the player first, so it is right even without
-     * `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).
+     * `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
      *
@@ -3011,11 +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, 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"
+     * 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,12 +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;
-        // 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")
+        // 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;
@@ -1119,10 +1125,10 @@ function slot(scope, name) {
         async toggle() {
             await service().read();
             const current = service().state[name];
-            // Collapsed at the edge of fullscreen: slide it out (see Panel.toggle).
-            const collapsed = current?.reason === "fullscreen";
+            // A switch (see Panel.toggle): nothing pops out in fullscreen.
             await service().set(name, {
-                visible: collapsed || !(current?.preferred ?? true),
+                visible: !(current?.preferred ?? true),
+                reveal: false,
             });
         },
         setDetached: (detached) => service().set(name, { detached }),

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