@vestra-player/sdk 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.6.3
+
+**Who must change: nobody.** Documentation only: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability, no player version needed.
+
+- **Examples name window handles after the window they name (its Slint file where there is one).** The API examples, guides, tutorials and example plugins no longer call a window handle `window`: `readmeWindow` for `ui/readme.slint`, `presetsWindow`, `thumbnailWindow`, `bookmarkWindow`, `blurWindow` and so on, in `plugin.windows.create(…)` and `host.window(…)` alike.
+
+## 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

@@ -115,7 +115,7 @@ type Call = {
  * import assert from "node:assert/strict";
  * declare const host: TestHost;
  * // ---cut---
- * await host.command("open-picture").run(); // the plugin calls window.show()
+ * await host.command("open-picture").run(); // the plugin calls pictureWindow.show()
  * const picture = host.window("picture");
  * assert.equal(picture.visible, true);
  * picture.emit("adjust", "brightness", 40); // fire a Slint callback
@@ -2746,11 +2746,11 @@ export declare class TestHost implements Transport {
      * declare const host: TestHost;
      * declare const expected: string;
      * // ---cut---
-     * const window = host.window("import");
-     * window.emit("load-file"); // the plugin reads and parses the file itself
-     * for (let i = 0; i < 100 && window.props["status-text"] !== expected; i++)
+     * const importWindow = host.window("import");
+     * importWindow.emit("load-file"); // the plugin reads and parses the file itself
+     * for (let i = 0; i < 100 && importWindow.props["status-text"] !== expected; i++)
      *   await host.settle(20);
-     * assert.equal(window.props["status-text"], expected);
+     * assert.equal(importWindow.props["status-text"], expected);
      * ```
      *
      * @capability None.
@@ -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.
@@ -3481,11 +3479,11 @@ export class TestHost {
      * declare const host: TestHost;
      * declare const expected: string;
      * // ---cut---
-     * const window = host.window("import");
-     * window.emit("load-file"); // the plugin reads and parses the file itself
-     * for (let i = 0; i < 100 && window.props["status-text"] !== expected; i++)
+     * const importWindow = host.window("import");
+     * importWindow.emit("load-file"); // the plugin reads and parses the file itself
+     * for (let i = 0; i < 100 && importWindow.props["status-text"] !== expected; i++)
      *   await host.settle(20);
-     * assert.equal(window.props["status-text"], expected);
+     * assert.equal(importWindow.props["status-text"], expected);
      * ```
      *
      * @capability None.
@@ -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

@@ -367,10 +367,10 @@ export interface Scope extends Disposable {
      *       return;
      *     }
      *     live = plugin.scope();
-     *     const window = live.windows.create("ui/stats.slint");
+     *     const statsWindow = live.windows.create("ui/stats.slint");
      *     const timer = setInterval(() => live?.update(), 1000);
      *     live.onDispose(() => clearInterval(timer));
-     *     await window.show();
+     *     await statsWindow.show();
      *   },
      * });
      * ```
@@ -487,12 +487,12 @@ export interface Scope extends Disposable {
      * promise settles; state changed between the awaits of a long handler
      * shows only after an explicit `update()`.
      * ```ts
-     * declare const window: Window;
+     * declare const downloadWindow: Window;
      * declare function downloadPart(part: number): Promise<void>;
      * // ---cut---
      * let done = 0;
-     * window.bind(() => ({ progress: done }));
-     * window.on("start", async () => {
+     * downloadWindow.bind(() => ({ progress: done }));
+     * downloadWindow.on("start", async () => {
      *   for (let part = 0; part < 10; part++) {
      *     await downloadPart(part);
      *     done = part + 1;
@@ -1682,11 +1682,11 @@ export interface Ui {
      * calls `image()` again after rewriting it, because the SDK does not send
      * a value that did not change.
      * ```ts
-     * const window = plugin.windows.create("ui/thumbnail.slint");
+     * const thumbnailWindow = plugin.windows.create("ui/thumbnail.slint");
      * const file = `${plugin.dataDirectory}/thumbnail.png`;
      * // … write the PNG to `file` (for example with plugin.tools.run("ffmpeg", …)) …
-     * window.set({ thumbnail: plugin.ui.image(file) });
-     * await window.show();
+     * thumbnailWindow.set({ thumbnail: plugin.ui.image(file) });
+     * await thumbnailWindow.show();
      * ```
      *
      * @since 1.0.0
@@ -1850,11 +1850,11 @@ export interface Ui {
      * const response = await fetch(readmeUrl);
      * if (!response.ok) throw new Error(`README: HTTP ${response.status}`);
      * const text = await response.text();
-     * const window = plugin.windows.create("ui/readme.slint");
+     * const readmeWindow = plugin.windows.create("ui/readme.slint");
      * // Bound before the first `show`, as a tool window requires.
-     * window.on("openLink", (url: string) => plugin.system.openUrl(url));
-     * window.set({ doc: await plugin.ui.markdown(text, { base: readmeUrl }) });
-     * await window.show();
+     * readmeWindow.on("openLink", (url: string) => plugin.system.openUrl(url));
+     * readmeWindow.set({ doc: await plugin.ui.markdown(text, { base: readmeUrl }) });
+     * await readmeWindow.show();
      * ```
      *
      * @since 1.1.0
@@ -1999,10 +1999,10 @@ export interface View {
      * sends the value even though it equals the one sent before, which is
      * what pulls a control the user moved back to the plugin's value.
      * ```ts
-     * const window = plugin.windows.create("ui/presets.slint");
+     * const presetsWindow = plugin.windows.create("ui/presets.slint");
      * let presetIndex = 0;
-     * window.on("presetChosen", (index: number) => {
-     *   if (index > 2) window.set({ presetIndex }); // "Custom" is not a preset
+     * presetsWindow.on("presetChosen", (index: number) => {
+     *   if (index > 2) presetsWindow.set({ presetIndex }); // "Custom" is not a preset
      *   else presetIndex = index;
      * });
      * ```
@@ -2165,9 +2165,9 @@ export interface Window extends View, Disposable {
      * window; it rejects with a code, such as `host` for a Slint file that
      * does not compile or `unavailable` without a user interface.
      * ```ts
-     * const window = plugin.windows.create("ui/inspector.slint");
+     * const inspectorWindow = plugin.windows.create("ui/inspector.slint");
      * try {
-     *   await window.show();
+     *   await inspectorWindow.show();
      * } catch (error) {
      *   // The code is data; `message` has the details for the log.
      *   await plugin.osd.show("Cannot open the inspector ({})", [(error as PluginError).code]);
@@ -2276,8 +2276,8 @@ export interface Window extends View, Disposable {
      * store writes the change to `window.json` shortly after.
      * ```ts
      * const store = plugin.storage.json("window", { defaults: { open: false } });
-     * const window = plugin.windows.create("ui/notes.slint");
-     * window.onClose(() => store.save({ open: false }));
+     * const notesWindow = plugin.windows.create("ui/notes.slint");
+     * notesWindow.onClose(() => store.save({ open: false }));
      * ```
      *
      * @see [Remember a window's state between runs](../../docs/how-to/window-state.md)
@@ -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
@@ -5370,9 +5390,9 @@ export interface Stream extends Disposable {
      * connection; it resolves once both are closed.
      * ```ts
      * declare const stream: Stream;
-     * declare const window: Window;
+     * declare const generatorWindow: Window;
      * // ---cut---
-     * window.onClose(() => stream.stop());
+     * generatorWindow.onClose(() => stream.stop());
      * ```
      *
      * @since 1.0.0
@@ -9640,10 +9660,10 @@ export interface JsonStore<T> extends Disposable {
      * writes the file only once the user stops for 300 ms. Each `save`
      * replaces the value and restarts the debounce timer.
      * ```ts
-     * declare const window: Window;
+     * declare const volumeWindow: Window;
      * // ---cut---
      * const store = plugin.storage.json("prefs", { defaults: { volume: 100 } });
-     * window.on("volumeChanged", (volume: number) => store.save({ ...store.value, volume }));
+     * volumeWindow.on("volumeChanged", (volume: number) => store.save({ ...store.value, volume }));
      * ```
      *
      * @since 1.0.0

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