@vestra-player/sdk 1.6.1 → 1.6.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.6.2
+
+**Who must change: nobody, but check `TestHost` tests of a full sidebar or of `keepsRunning` with a background tab.** No change to the TypeScript API or the wire, `apiVersion` stays `vestra/1`, no new capability, no player version needed. `TestHost` follows player 0.7.3: it no longer refuses a ninth sidebar tab, and `keepsRunning` lists a sidebar panel only while its tab is the current tab, as `"its sidebar tab is the current tab"`. A test that expected `conflict` for a ninth tab, or `"a mounted panel"` for a sidebar panel, now fails.
+
+- **Sidebar tabs without a limit** (player 0.7.3; the player's [sidebar tabs design](https://github.com/vestrasys/vestra-player/blob/main/doc/architecture/sidebar-tabs.md)). The sidebar takes any number of tabs: the strip shows the tabs that fit and a `»` menu at its end lists all of them, the current one checked. Players 0.4.x to 0.7.2 refused a ninth tab with `conflict` (「侧栏最多 8 个页签」); player 0.7.3 never refuses a sidebar mount for that. `Panel.ready`, [Windows, panels, settings pages, dialogs and the OSD](docs/explanation/ui.md#shared-space) and `TestHost` say so. The SDK's copy of the player's Chinese texts (`HOST_ZH_HANS`) drops "The sidebar holds at most {} tabs", which the player no longer has.
+- **A background tab does not keep its plugin running** (player 0.7.3). The current tab keeps its plugin running as busy work; a sidebar panel never makes a plugin resident. A plugin whose sidebar panel is in a background tab, and that holds nothing else that keeps it running, goes to standby after the idle time like any idle plugin (stop reason `idle`); the player keeps its tab, with its title, in the strip and the `»` menu. Showing the tab starts the plugin again: `activate` runs and mounts the same panel (same file and component), which takes the tab over, and `Panel.ready` resolves again. The new process mounts with the properties its `activate` passes, so keep what the panel shows in session storage, the only state that survives standby, and restore it in `activate`. `Panel.state`, [Windows, panels…](docs/explanation/ui.md#panel), [How a plugin runs › Idle plugins are stopped](docs/explanation/plugins.md#idle-plugins-are-stopped) and [How the player runs and talks to plugins](docs/explanation/host-and-node.md) (the recorded `ui.mount`, the `panel_shown` wake) describe it. `TestHost.keepsRunning` lists `"its sidebar tab is the current tab"` while it is, and nothing for a background tab; `"a mounted panel"` is now for the bottom bar and the backdrop only.
+
 ## 1.6.1
 
 **Who must change: nobody.** Docs only: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability.

package/dist/i18n.js

@@ -943,7 +943,6 @@ export const HOST_ZH_HANS = {
     sidebar: "侧栏",
     "video backdrop": "视频背景",
     "The {} is used by {}": "{}已被 {} 使用",
-    "The sidebar holds at most {} tabs": "侧栏最多 {} 个页签",
     "{} is resolved by {}": "{} 已由 {} 解析",
     "File type .{}": "文件类型 .{}",
     "Not available in fullscreen": "全屏时不可用",

package/dist/plugin/testing.d.ts

@@ -2782,12 +2782,18 @@ export declare class TestHost implements Transport {
     close(): void;
     /**
      * Why the player would keep this plugin running while nothing uses it
-     * (lazy activation, player 0.5.21), one line per reason, as the player's
-     * log says it: an event it listens to that is not one the player wakes
-     * it for (with what listens and where it was added), its mounted panel,
-     * its open windows. Empty: the player may stop it while idle and start
-     * it again on its next use. Filter chains, streams, jobs and the like
-     * (which also keep a plugin running) are not listed.
+     * (lazy activation, player 0.5.21), one line per reason: an event it
+     * listens to that is not one the player wakes it for (with what listens
+     * and where it was added), its panel in the bottom bar or the backdrop,
+     * its open windows (these as the player's log says them), and, from
+     * player 0.7.3, its sidebar tab while that is the current tab. The
+     * player counts the current tab as busy work, not as something live: it
+     * keeps the plugin running only while the tab is shown, and a sidebar
+     * panel in a background tab is no reason at all (the plugin may go to
+     * standby; showing the tab starts it again). Empty: the player may stop
+     * it while idle and start it again on its next use. Filter chains,
+     * streams, jobs and the like (which also keep a plugin running) are not
+     * listed.
      *
      * @capability None.
      * @since 1.5.40

package/dist/plugin/testing.js

@@ -314,8 +314,6 @@ const TEST_ZH_HANS = {
     "External SRT": "外部 SRT",
     "External ASS": "外部 ASS",
 };
-/** The player's limit of sidebar tabs. */
-const MAX_SIDEBAR_TABS = 8;
 /**
  * The player's refusal of a declaration (commands.rs `CommandError`): code
  * `invalid`, `conflict` or `limit`, its message prefixed as the player's.
@@ -3983,12 +3981,18 @@ export class TestHost {
     }
     /**
      * Why the player would keep this plugin running while nothing uses it
-     * (lazy activation, player 0.5.21), one line per reason, as the player's
-     * log says it: an event it listens to that is not one the player wakes
-     * it for (with what listens and where it was added), its mounted panel,
-     * its open windows. Empty: the player may stop it while idle and start
-     * it again on its next use. Filter chains, streams, jobs and the like
-     * (which also keep a plugin running) are not listed.
+     * (lazy activation, player 0.5.21), one line per reason: an event it
+     * listens to that is not one the player wakes it for (with what listens
+     * and where it was added), its panel in the bottom bar or the backdrop,
+     * its open windows (these as the player's log says them), and, from
+     * player 0.7.3, its sidebar tab while that is the current tab. The
+     * player counts the current tab as busy work, not as something live: it
+     * keeps the plugin running only while the tab is shown, and a sidebar
+     * panel in a background tab is no reason at all (the plugin may go to
+     * standby; showing the tab starts it again). Empty: the player may stop
+     * it while idle and start it again on its next use. Filter chains,
+     * streams, jobs and the like (which also keep a plugin running) are not
+     * listed.
      *
      * @capability None.
      * @since 1.5.40
@@ -4012,7 +4016,13 @@ export class TestHost {
             if (!WAKE_EVENTS.includes(event))
                 for (const why of this.listeningWhy.get(event) ?? ["a listener"])
                     reasons.push(`listens to ${event}: ${why}`);
-        if (this.panel)
+        // A sidebar panel is never live (player 0.7.3): the current tab keeps
+        // the plugin running as busy work, a background tab not at all.
+        if (this.panel?.slot === "sidebar") {
+            if (this.layout.sidebar?.owner === 1)
+                reasons.push("its sidebar tab is the current tab");
+        }
+        else if (this.panel)
             reasons.push("a mounted panel");
         for (const [id, window] of this.windows)
             if (window.visible)
@@ -4234,8 +4244,8 @@ export class TestHost {
         "ui.mount": (p) => {
             if (this.panel)
                 throw new HostError("conflict", "owner already mounted");
-            // Like the player: one panel in the bottom bar and the backdrop, tabs
-            // in the sidebar (up to 8).
+            // Like the player: one panel in the bottom bar and the backdrop, any
+            // number of tabs in the sidebar (player 0.7.3; 0.4.x to 0.7.2 took 8).
             const holder = p.slot === "backdrop"
                 ? this.backdrop?.owner
                 : p.slot === "bottom"
@@ -4246,11 +4256,6 @@ export class TestHost {
                     this.#hostText(SLOT_LABELS[String(p.slot)]),
                     String(holder),
                 ]));
-            if (p.slot === "sidebar" &&
-                (this.layout.sidebar?.panels?.length ?? 0) >= MAX_SIDEBAR_TABS)
-                throw taken(this.#hostText("The sidebar holds at most {} tabs", [
-                    MAX_SIDEBAR_TABS,
-                ]));
             const properties = this.#initialValues(this.#shownValues(p.properties));
             this.#seeImages(properties);
             this.#resetWrites("$mount");

package/dist/plugin/types.d.ts

@@ -2732,15 +2732,22 @@ export interface Panel extends View, Disposable {
      * A second sidebar panel is not refused: it resolves as another tab
      * (see {@link Panel.state}). Built-in plugins mount first at start-up,
      * so the playlist's tab is first and a built-in panel keeps its position.
+     * Behaviour from player 0.7.3: the sidebar takes any number of tabs; the
+     * strip shows the tabs that fit and a `»` menu lists all of them.
+     * Players 0.4.x to 0.7.2 refused a ninth tab with `conflict`. A plugin
+     * whose sidebar tab is in the background, and that holds nothing else
+     * that keeps it running, goes to standby when idle; showing the tab
+     * starts it again (see {@link Panel.state}).
      *
      * @throws `ui-prepare` (rejects) The Slint file does not compile, or a
      *   bound property is not declared on the bridge global; `message` has the
      *   diagnostics. (Players 0.4.0 and older also answer a taken bottom bar
      *   or sidebar with it.)
      * @throws `conflict` (rejects) Another plugin's panel holds the bottom bar
-     *   or the backdrop (shown, or being mounted), or the sidebar has all the
-     *   tabs it takes (8); `message` names the position and the holder
-     *   (「侧栏已被 vestra.playlist 使用」). Not an activation failure.
+     *   or the backdrop (shown, or being mounted); `message` names the
+     *   position and the holder (「底栏已被 vestra.playback 使用」). Not an
+     *   activation failure. Never for the sidebar (behaviour from player
+     *   0.7.3); players 0.4.x to 0.7.2 also refused a ninth sidebar tab.
      * @throws `busy` (rejects) The player is still preparing this plugin's
      *   previous mount, or its queue of mounts is full.
      * @throws `invalid` (rejects) `title` is longer than 128 bytes or has
@@ -2761,6 +2768,19 @@ export interface Panel extends View, Disposable {
      * only this plugin's own changes. A sidebar panel in a background tab
      * has `active: false`, `effective: false` and `reason: "otherTab"`.
      *
+     * Behaviour from player 0.7.3: a background tab does not keep the plugin
+     * running.
+     * If the panel is all that keeps it running, the plugin goes to standby
+     * after the idle time (stop reason `idle`): the player keeps its tab, with
+     * its title, in the strip and the `»` menu. When the user shows the tab,
+     * the player starts the plugin again; `activate` runs and mounts the same
+     * panel (same file and component), which takes the tab over, and
+     * {@link Panel.ready} resolves again. Anything the plugin kept only in
+     * memory is gone: restore the view from storage (session storage
+     * survives standby). While it is in the background, the player may also
+     * drop the panel's component and build it again from the bridge
+     * properties last written, as it does on any rebuild.
+     *
      * @throws Never; `null` stands for "not mounted".
      *
      * @since 1.5.2

package/llms.txt

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