@vestra-player/sdk 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.5.2
+
+**Sidebar tabs** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.1 need no change. The new members work against older players too (see each one).
+
+- **Several sidebar panels.** A plugin mounting in the sidebar while another plugin's panel is there no longer fails: its `ready` resolves and the panel is a second tab. The player draws a 31px tab strip (the playlist's) above the current tab while there are two or more; with one panel nothing changes. Shown, hidden and floating apply to the whole sidebar. Tabs are labelled with the mount's `title` (else the plugin's name); built-in plugins' tabs come first, the playlist's is the first.
+- **`Panel.state`** (`PanelState`: `active`, `preferred`, `effective`, `reason`, `detached`) and **`Panel.onChange`**: the panel's own state. A panel in a background tab has `active: false`, `effective: false` and `reason: "otherTab"`. Older players report the position's state with `active: true`.
+- **`Panel.show()`** makes the panel's tab current and shows the sidebar; **`Panel.toggle()`** hides the sidebar when the panel's tab is shown, otherwise shows it (a background tab comes forward). Use them for a "Show my panel" command: `checked: () => !!list.state?.preferred && !!list.state?.active`. Older players: `setVisible(true)` / `toggle()` of the position.
+- **`PanelSlot.panels`** (`SlotPanel[]`: `plugin`, `title`, `active`) lists a position's tabs, `null` from older players; `PanelSlot.onChange` also runs when only the tabs change. **`PanelSlot.activate(plugin)`** switches the current tab (older players ignore it). `SlotState` is unchanged.
+- **The `tabbed` property.** If a sidebar panel's bridge global declares `in property <bool> tabbed`, the player sets it to `true` while it draws its tab strip, so a panel with a tab strip of its own (the playlist) hides it. Drop coordinates (`Panel.onDrop`) start below the strip.
+- **`Panel.showMenu`** in a background tab rejects with `unavailable`.
+- **Taken positions** (player 0.4.x after 0.4.0, documented now): the bottom bar and the backdrop take one panel; another plugin's mount there rejects `ready` with `conflict` (「底栏已被 vestra.playback 使用」), as does a ninth sidebar tab. This refusal, and `conflict` from `player.provideSequence` while another plugin provides next/previous, do not fail activation in the player: the plugin runs without its panel or sequence. Players 0.4.0 and older answered a taken bottom bar or sidebar with `ui-prepare` and failed the activation.
+- **`PluginInfo.warnings`** (`PluginWarning`: `code` `"slot-occupied"` or `"sequence-taken"`, `slot`, `owner`): what a running plugin was refused because another plugin holds it. Empty from older players.
+- **`TestHost`** models both: `host.mountOther(slot, plugin, { title })` and `host.unmountOther(plugin)` simulate another plugin's panel (a sidebar tab, or a taken bottom bar or backdrop: the plugin's mount then rejects with `conflict`), `host.selectTab(plugin)` the user clicking a tab; `host.layout.sidebar.panels` / `.owner` are the tabs and the current one, `layout.set` takes `active`. `startPlugin` does not fail on a taken position, like the player.
+- Examples: panel-menu no longer asks you not to load it with the playlist; it is a second tab there. Its list ends in a stretching filler: without it the rows' fixed heights capped the player's main window at its minimum height.
+
+## 1.5.1
+
+Fix; no API or type changes.
+
+- **`storage.json` saves no longer collide.** Every save wrote through the same temporary file (`<name>.json.tmp-<pid>`), and only the writes of one store were queued. Two stores on the same file (the same name opened twice, in one scope or two) could therefore rename each other's temporary file away mid-save, and the save failed with `ENOENT` (on `chmod` or `rename`); on Windows two renames onto the file at once also fail with `EPERM`. Seen intermittently on Windows.
+  - Writes to one file are now queued together, whichever store makes them, and land in the order they were made.
+  - Each write has a temporary file of its own, made owner-only (`0600`) through its file handle before it gets the store's name, and removed again if the write fails.
+  - On Windows, replacing the file is retried for up to 2 s while another program (a virus scanner, the search indexer) briefly holds it open.
+
 ## 1.5.0
 
 **Own visual identity: the Aurora palettes and the V-Line icons** (player 0.4.0). Additive; `apiVersion` stays `vestra/1`. Plugins that use the additions set `"minPlayerVersion": "0.4.0"`.

package/README.md

@@ -33,7 +33,13 @@ npm i -D @vestra-player/sdk   # Node.js 26 or newer
 `manifest.json` and `main.ts`:
 
 ```json
-{ "id": "examples.hello", "version": "0.1.0", "apiVersion": "vestra/1", "entry": "main.ts", "capabilities": ["commands", "ui.osd"] }
+{
+  "id": "examples.hello",
+  "version": "0.1.0",
+  "apiVersion": "vestra/1",
+  "entry": "main.ts",
+  "capabilities": ["commands", "ui.osd"]
+}
 ```
 
 ```ts
@@ -54,33 +60,34 @@ Run `npx vestra-plugin pack` to check and package it, or start the player with `
 
 Complete, tested plugins in [`examples/`](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples). The [examples page](https://vestrasys.github.io/vestra-player-sdk/documents/Examples.html) shows each one with a screenshot and a step-by-step walkthrough.
 
-| Example | What you learn | Walkthrough |
-| --- | --- | --- |
-| [hello](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/hello) | The smallest plugin: a manifest, one menu command, an on-screen message. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Hello.html) |
-| [blur](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/blur) | Video filters, a tool window with live controls, a shortcut, a settings page, remembered state. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Blur.html) |
-| [signal-generator](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/signal-generator) | Generating video and audio frames yourself, phase-continuous audio, audio filters, stream lifecycle. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Signal_generator.html) |
-| [bookmark](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/bookmark) | Reading and controlling playback from a tool window. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Bookmark.html) |
-| [panel-menu](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/panel-menu) | A sidebar panel with its own context menu, panel-only keys and next/previous. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Panel_menu.html) |
-| [core-ui](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/core-ui) | Menus (radio items, groups, changing titles), repeating keys, the shared sidebar, theme widgets. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Core_UI.html) |
-| [markdown](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/markdown) | The Markdown view with local and remote images; the manifest's display fields. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Markdown.html) |
+| Example                                                                                                | What you learn                                                           | Walkthrough                                                                                            |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| [hello](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/hello)                       | The smallest plugin: a manifest, one menu command, an on-screen message. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Hello.html)                     |
+| [blur](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/blur)                         | A video filter driven by one slider in a tool window.                    | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Blur.html)             |
+| [signal-generator](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/signal-generator) | Generating video and audio frames yourself: colour bars and a sine tone. | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Signal_generator.html) |
+| [bookmark](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/bookmark)                 | A tool window bound to the playback state, with Mark and Jump buttons.   | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Bookmark.html)         |
+| [panel-menu](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/panel-menu)             | A sidebar panel with its own right-click menu.                           | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Panel_menu.html)       |
+| [menus](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/menus)                       | Radio items, separator groups and a menu item whose title changes.       | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Menus.html)            |
+| [theme-widgets](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/theme-widgets)       | A tool window drawn with the player's theme and widgets.                 | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Theme_widgets.html)    |
+| [markdown](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples/markdown)                 | A window that shows a Markdown document.                                 | [Step by step](https://vestrasys.github.io/vestra-player-sdk/documents/Example__Markdown.html)         |
 
 ## Command line
 
-| Command | Does |
-| --- | --- |
-| `vestra-plugin check [dir...]` | Checks the manifest, then a strict type check of the plugin and its tests. |
-| `vestra-plugin test [dir...]` | Runs `node --test` on `tests/*.test.{ts,mjs}`. |
-| `vestra-plugin build [dir...] [--version x.y.z]` | Writes `dist/`: types stripped, files copied, manifest versioned. |
-| `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]` | Builds, then packs `dist/` as `<id>-<version>.vxp`. |
+| Command                                                     | Does                                                                       |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `vestra-plugin check [dir...]`                              | Checks the manifest, then a strict type check of the plugin and its tests. |
+| `vestra-plugin test [dir...]`                               | Runs `node --test` on `tests/*.test.{ts,mjs}`.                             |
+| `vestra-plugin build [dir...] [--version x.y.z]`            | Writes `dist/`: types stripped, files copied, manifest versioned.          |
+| `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]` | Builds, then packs `dist/` as `<id>-<version>.vxp`.                        |
 
 ## Compatibility
 
-| SDK | Plugin API | Vestra Player | Node.js |
-| --- | --- | --- | --- |
-| 1.0 | `vestra/1` | 0.1 or newer | 22.18 or newer |
-| 1.1 | `vestra/1` | 0.2 or newer for the 1.1 additions | 22.18 or newer |
-| 1.2 | `vestra/1` | 0.2 or newer | 26 (shipped with the player) |
-| 1.3 | `vestra/1` | 0.2 or newer; 0.3 for the 1.3 additions (menu ids, `Theme.danger`, empty video chains) | 26 (shipped with the player) |
+| SDK | Plugin API | Vestra Player                                                                             | Node.js                      |
+| --- | ---------- | ----------------------------------------------------------------------------------------- | ---------------------------- |
+| 1.0 | `vestra/1` | 0.1 or newer                                                                              | 22.18 or newer               |
+| 1.1 | `vestra/1` | 0.2 or newer for the 1.1 additions                                                        | 22.18 or newer               |
+| 1.2 | `vestra/1` | 0.2 or newer                                                                              | 26 (shipped with the player) |
+| 1.3 | `vestra/1` | 0.2 or newer; 0.3 for the 1.3 additions (menu ids, `Theme.danger`, empty video chains)    | 26 (shipped with the player) |
 | 1.4 | `vestra/1` | 0.2 or newer; 0.3 for the 1.3 additions. `ThemeId` is `"vestra"` only (see the CHANGELOG) | 26 (shipped with the player) |
 | 1.5 | `vestra/1` | 0.2 or newer; 0.3 for the 1.3 additions; 0.4 for the 1.5 additions (`vestra-light`, `@vestra/icons.slint`) | 26 (shipped with the player) |
 

package/dist/plugin/packages.js

@@ -220,4 +220,9 @@ const info = (plugin) => Object.freeze({
     builtin: plugin.builtin === true,
     source: plugin.source ? Object.freeze({ ...plugin.source }) : null,
     dataDirectory: plugin.dataDirectory ?? null,
+    warnings: Object.freeze((plugin.warnings ?? []).map((warning) => Object.freeze({
+        code: warning.code,
+        ...(warning.slot === undefined ? {} : { slot: warning.slot }),
+        ...(warning.owner === undefined ? {} : { owner: warning.owner }),
+    }))),
 });

package/dist/plugin/services.js

@@ -4,7 +4,7 @@
  * run in this plugin's own process.
  */
 import { existsSync, readFileSync, renameSync } from "node:fs";
-import { chmod, mkdir, rename, stat, writeFile } from "node:fs/promises";
+import { mkdir, open, rename, rm, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { failure } from "./runtime.js";
 import { systemServices } from "./local.js";
@@ -101,6 +101,54 @@ export function tools(scope) {
     };
 }
 const NAME = /^[a-z0-9-]{1,64}$/;
+/** Writes so far in this process; numbers each write's temporary file. */
+let written = 0;
+/**
+ * The pending writes of each file, whichever store they come from: the same
+ * name opened twice must not write or rename into one file at once.
+ */
+const writes = new Map();
+/** Write `text` to `path` atomically, owner-only (0600). */
+async function writeAtomic(path, text) {
+    // A name of its own per write, so no other write renames it away.
+    const temporary = `${path}.tmp-${process.pid}-${++written}`;
+    await mkdir(join(path, ".."), { recursive: true });
+    try {
+        // Settings can hold private paths and history. The mode is set through
+        // the handle, before the file has its name.
+        const file = await open(temporary, "w", 0o600);
+        try {
+            await file.chmod(0o600);
+            await file.writeFile(text);
+        }
+        finally {
+            await file.close();
+        }
+        await replace(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+/**
+ * Rename over `to`. Windows refuses while another program (a virus scanner,
+ * the search indexer) has `to` open for a moment: retry for up to 2 s there.
+ */
+async function replace(from, to) {
+    for (let attempt = 0;; attempt++)
+        try {
+            return await rename(from, to);
+        }
+        catch (error) {
+            const code = error.code;
+            if (process.platform !== "win32" ||
+                !(code === "EPERM" || code === "EACCES" || code === "EBUSY") ||
+                attempt >= 20)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 10 + attempt * 10));
+        }
+}
 class Store {
     #scope;
     #path;
@@ -159,17 +207,19 @@ class Store {
             return this.#writing;
         this.#dirty = false;
         const text = `${JSON.stringify(this.#value, null, 2)}\n`;
-        // One write at a time, in order; the newest value is written last.
-        this.#writing = this.#writing
+        // One write per file at a time, in order; the newest value is written
+        // last. The queue is per file, not per store (see `writes`).
+        const path = this.#path;
+        const write = (writes.get(path) ?? Promise.resolve())
             .catch(() => { })
-            .then(async () => {
-            const temporary = `${this.#path}.tmp-${process.pid}`;
-            await mkdir(join(this.#path, ".."), { recursive: true });
-            // Owner-only: settings can hold private paths and history.
-            await writeFile(temporary, text, { mode: 0o600 });
-            await chmod(temporary, 0o600);
-            await rename(temporary, this.#path);
-        });
+            .then(() => writeAtomic(path, text));
+        const done = () => {
+            if (writes.get(path) === write)
+                writes.delete(path);
+        };
+        writes.set(path, write);
+        write.then(done, done);
+        this.#writing = write;
         return this.#writing;
     }
     async dispose() {

package/dist/plugin/testing.d.ts

@@ -238,9 +238,16 @@ export declare class TestHost implements Transport {
      * ```
      */
     readonly layout: {
-        /** The bottom bar position: `preferred`, `effective`, `reason`, `detached`. */
+        /**
+         * The bottom bar position: `preferred`, `effective`, `reason`,
+         * `detached`, `owner` and `panels` (its one panel).
+         */
         bottom: LayoutSlot | null;
-        /** The sidebar position: `preferred`, `effective`, `reason`, `detached`. */
+        /**
+         * The sidebar position: `preferred`, `effective`, `reason`, `detached`;
+         * `panels` are its tabs in order (`{ owner, plugin, title }`), `owner`
+         * the current tab's (the plugin under test is owner 1).
+         */
         sidebar: LayoutSlot | null;
     };
     /** Every `osd.show` text, newest last. */
@@ -554,6 +561,46 @@ export declare class TestHost implements Transport {
      * appeared; `true`: there is none again); pushed to the plugin.
      */
     setBackdropEffective(effective: boolean): void;
+    /**
+     * Simulate another plugin mounting a panel, before or after the plugin
+     * under test, as the player handles it: in the sidebar it is another tab
+     * (after the existing ones; the first panel's tab is current); the bottom
+     * bar and the backdrop take one panel, so the plugin's own mount there
+     * then rejects with `conflict` (not an activation failure, as in the
+     * player). Pushed as a `window.state` change.
+     *
+     * @param slot - The position.
+     * @param plugin - The other plugin's manifest id.
+     * @param options - `title`: its tab label (default: `plugin`).
+     *
+     * @example The playlist next to this plugin's sidebar panel
+     * ```ts
+     * const host = new TestHost();
+     * host.mountOther("sidebar", "vestra.playlist", { title: "播放列表" });
+     * const { plugin } = await startPlugin(activate, { host, directory });
+     * assert.equal(host.layout.sidebar?.panels?.length, 2);
+     * ```
+     *
+     * @since 1.5.2
+     */
+    mountOther(slot: "bottom" | "sidebar" | "backdrop", plugin: string, options?: {
+        title?: string;
+    }): void;
+    /**
+     * Simulate another plugin's panel going away ({@link TestHost.mountOther}):
+     * when its tab was current, the next tab (else the previous one) is.
+     *
+     * @since 1.5.2
+     */
+    unmountOther(plugin: string): void;
+    /**
+     * Simulate the user clicking a sidebar tab: `plugin`'s panel (the plugin
+     * under test's `manifestId`, or one of {@link TestHost.mountOther})
+     * becomes the current tab. Pushed as a `window.state` change.
+     *
+     * @since 1.5.2
+     */
+    selectTab(plugin: string): void;
     /**
      * The display layer (`plugin.video.view()`): who owns it (this plugin is
      * `manifestId`) and the values the player holds.

package/dist/plugin/testing.js

@@ -110,6 +110,20 @@ const readyCapabilities = {
     close: true,
     snapshotSource: true,
 };
+/** Refusals for a position another plugin holds: not activation failures (`startPlugin`). */
+const takenErrors = new WeakSet();
+const taken = (message) => {
+    const error = new HostError("conflict", message);
+    takenErrors.add(error);
+    return error;
+};
+const SLOT_LABELS = {
+    bottom: "底栏",
+    sidebar: "侧栏",
+    backdrop: "视频背景",
+};
+/** The player's limit of sidebar tabs. */
+const MAX_SIDEBAR_TABS = 8;
 /**
  * An in-memory fake Vestra Player for plugin tests.
  *
@@ -531,6 +545,109 @@ export class TestHost {
             this.backdrop.effective = effective;
         this.emit("window.state", this.#windowFacts());
     }
+    #nextOwner = 2;
+    /** Owners of other plugins' panels, by plugin id ({@link TestHost.mountOther}). */
+    #others = new Map();
+    /**
+     * Simulate another plugin mounting a panel, before or after the plugin
+     * under test, as the player handles it: in the sidebar it is another tab
+     * (after the existing ones; the first panel's tab is current); the bottom
+     * bar and the backdrop take one panel, so the plugin's own mount there
+     * then rejects with `conflict` (not an activation failure, as in the
+     * player). Pushed as a `window.state` change.
+     *
+     * @param slot - The position.
+     * @param plugin - The other plugin's manifest id.
+     * @param options - `title`: its tab label (default: `plugin`).
+     *
+     * @example The playlist next to this plugin's sidebar panel
+     * ```ts
+     * const host = new TestHost();
+     * host.mountOther("sidebar", "vestra.playlist", { title: "播放列表" });
+     * const { plugin } = await startPlugin(activate, { host, directory });
+     * assert.equal(host.layout.sidebar?.panels?.length, 2);
+     * ```
+     *
+     * @since 1.5.2
+     */
+    mountOther(slot, plugin, options = {}) {
+        if (this.#others.has(plugin))
+            throw new Error(`${plugin} already has a panel`);
+        const owner = this.#nextOwner++;
+        if (slot === "backdrop") {
+            if (this.backdrop)
+                throw new Error("the backdrop is taken");
+            this.backdrop = { owner: plugin, effective: true };
+        }
+        else {
+            if (slot === "bottom" && this.layout.bottom)
+                throw new Error("the bottom bar is taken");
+            this.#addPanel(slot, { owner, plugin, title: options.title ?? plugin });
+        }
+        this.#others.set(plugin, { slot, owner });
+        this.emit("window.state", this.#windowFacts());
+    }
+    /**
+     * Simulate another plugin's panel going away ({@link TestHost.mountOther}):
+     * when its tab was current, the next tab (else the previous one) is.
+     *
+     * @since 1.5.2
+     */
+    unmountOther(plugin) {
+        const other = this.#others.get(plugin);
+        if (!other)
+            throw new Error(`${plugin} has no panel`);
+        this.#others.delete(plugin);
+        if (other.slot === "backdrop")
+            this.backdrop = null;
+        else
+            this.#removePanel(other.slot, other.owner);
+        this.emit("window.state", this.#windowFacts());
+    }
+    /**
+     * Simulate the user clicking a sidebar tab: `plugin`'s panel (the plugin
+     * under test's `manifestId`, or one of {@link TestHost.mountOther})
+     * becomes the current tab. Pushed as a `window.state` change.
+     *
+     * @since 1.5.2
+     */
+    selectTab(plugin) {
+        const slot = this.layout.sidebar;
+        const panel = slot?.panels?.find((entry) => entry.plugin === plugin);
+        if (!slot || !panel)
+            throw new Error(`${plugin} has no sidebar tab`);
+        slot.owner = panel.owner;
+        this.emit("window.state", this.#windowFacts());
+    }
+    #addPanel(slot, panel) {
+        const state = this.layout[slot];
+        if (state)
+            state.panels = [...(state.panels ?? []), panel];
+        else
+            this.layout[slot] = {
+                owner: panel.owner,
+                preferred: true,
+                effective: true,
+                reason: null,
+                detached: false,
+                panels: [panel],
+            };
+    }
+    #removePanel(slot, owner) {
+        const state = this.layout[slot];
+        if (!state)
+            return;
+        const panels = state.panels ?? [];
+        const index = panels.findIndex((panel) => panel.owner === owner);
+        const rest = panels.filter((panel) => panel.owner !== owner);
+        if (rest.length === 0) {
+            this.layout[slot] = null;
+            return;
+        }
+        state.panels = rest;
+        if (state.owner === owner)
+            state.owner = (rest[index] ?? rest[rest.length - 1]).owner;
+    }
     /**
      * The display layer (`plugin.video.view()`): who owns it (this plugin is
      * `manifestId`) and the values the player holds.
@@ -1710,8 +1827,18 @@ export class TestHost {
         "ui.mount": (p) => {
             if (this.panel)
                 throw new HostError("conflict", "owner already mounted");
-            if (p.slot === "backdrop" && this.backdrop)
-                throw new HostError("conflict", "another plugin shows the backdrop");
+            // Like the player: one panel in the bottom bar and the backdrop, tabs
+            // in the sidebar (up to 8).
+            const holder = p.slot === "backdrop"
+                ? this.backdrop?.owner
+                : p.slot === "bottom"
+                    ? this.layout.bottom?.panels?.[0]?.plugin
+                    : undefined;
+            if (holder !== undefined || (p.slot === "bottom" && this.layout.bottom))
+                throw taken(`${SLOT_LABELS[String(p.slot)]}已被 ${holder} 使用`);
+            if (p.slot === "sidebar" &&
+                (this.layout.sidebar?.panels?.length ?? 0) >= MAX_SIDEBAR_TABS)
+                throw taken(`侧栏最多 ${MAX_SIDEBAR_TABS} 个页签`);
             this.#seeImages(p.properties);
             const host = this;
             this.panel = {
@@ -1734,25 +1861,25 @@ export class TestHost {
                 return { status: "ready", prepareMs: 0, shellGeneration: 1 };
             }
             const slot = String(p.slot);
-            this.layout[slot] = {
+            this.#addPanel(slot, {
                 owner: 1,
-                preferred: true,
-                effective: true,
-                reason: null,
-                detached: false,
-            };
+                plugin: this.manifestId,
+                title: typeof p.title === "string" && p.title ? p.title : this.manifestId,
+            });
             return { status: "ready", prepareMs: 0, shellGeneration: 1 };
         },
         "ui.unmount": () => {
             if (this.panel?.slot === "backdrop")
                 this.backdrop = null;
             else if (this.panel)
-                this.layout[this.panel.slot] = null;
+                this.#removePanel(this.panel.slot, 1);
             this.panel = null;
         },
         "ui.menu": (p) => {
             if (!this.panel)
                 throw new HostError("unavailable", "panel not shown");
+            if (this.panel.slot === "sidebar" && this.layout.sidebar?.owner !== 1)
+                throw new HostError("unavailable", "the panel's tab is not the current one");
             const items = p.items;
             for (const id of items)
                 if (id !== null && !this.commands.has(id))
@@ -1773,6 +1900,12 @@ export class TestHost {
                 throw new HostError("missing", "no panel at this position");
             if (p.detached !== undefined && slot === "bottom")
                 throw new HostError("invalid", "the bottom bar cannot be detached");
+            if (p.active !== undefined && p.active !== null) {
+                const panel = state.panels?.find((entry) => entry.plugin === p.active);
+                if (!panel)
+                    throw new HostError("missing", `${String(p.active)} has no panel at this position`);
+                state.owner = panel.owner;
+            }
             if (typeof p.visible === "boolean") {
                 state.preferred = p.visible;
                 state.effective = p.visible;
@@ -2756,7 +2889,17 @@ export async function startPlugin(activate, options = {}) {
     mkdirSync(data, { recursive: true });
     const instance = await createPlugin(host, manifest, directory, data, host.app);
     await activate(instance.plugin);
-    await instance.activated();
+    // Like the player: a position another plugin holds is not an activation failure.
+    for (;;) {
+        try {
+            await instance.activated();
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof Error && takenErrors.has(error)))
+                throw error;
+        }
+    }
     await host.settle();
     return {
         /** The test host the plugin talks to. */

package/dist/plugin/types.d.ts

@@ -1212,6 +1212,46 @@ export interface SlotState {
     /** The sidebar floats in its own window; always `false` for the bottom bar. */
     detached: boolean;
 }
+/**
+ * One panel of a position ({@link PanelSlot.panels}): a tab of the sidebar.
+ *
+ * @since 1.5.2
+ * @category UI
+ */
+export interface SlotPanel {
+    /** The manifest id of the plugin that mounted it (pass it to {@link PanelSlot.activate}). */
+    plugin: string;
+    /** Its tab label: the `title` of {@link Panels.mount}, else the plugin's name. */
+    title: string;
+    /** Its tab is the current one (the panel the position shows). */
+    active: boolean;
+}
+/**
+ * The state of one panel ({@link Panel.state}): its position's state, seen
+ * from this panel, which may be one of several sidebar tabs.
+ *
+ * @since 1.5.2
+ * @category UI
+ */
+export interface PanelState {
+    /**
+     * Its tab is the current one. Always `true` for the bottom bar, the
+     * backdrop and a sidebar panel without other tabs.
+     */
+    active: boolean;
+    /** The position's preference (the user's choice to show it). */
+    preferred: boolean;
+    /** This panel is on screen now: the position is, and this is its current tab. */
+    effective: boolean;
+    /**
+     * Why this panel is not on screen, `null` while it is: `otherTab` while
+     * another plugin's tab is the current one (whatever the position's state),
+     * else the position's reason ({@link SlotState.reason}).
+     */
+    reason: SlotState["reason"] | "otherTab";
+    /** The sidebar floats in its own window (with all its tabs). */
+    detached: boolean;
+}
 /**
  * The bottom bar or the sidebar position (`plugin.panels.bottom`,
  * `plugin.panels.sidebar`), independent of who mounted the panel there.
@@ -1229,23 +1269,48 @@ export interface SlotState {
  *
  * @capability ui.mount; `events` to follow changes made elsewhere.
  *
- * @example A "Show sidebar" menu item that works with any sidebar panel (examples/core-ui)
- * {@includeCode ../../examples/core-ui/main.ts#sidebar}
+ * @example A "Show sidebar" menu item that works with any sidebar panel
+ * ```ts
+ * const sidebar = plugin.panels.sidebar;
+ * plugin.commands.add({
+ *   id: "sidebar",
+ *   path: ["Tools", "Show sidebar"],
+ *   checked: () => sidebar.state?.preferred ?? false,
+ *   enabled: () => sidebar.state !== null,
+ *   run: () => sidebar.toggle(),
+ * });
+ * ```
  *
  * @see {@link Panels}, {@link SlotState}
  * @since 1.0.0
  * @category UI
  */
 export interface PanelSlot {
-    /** The current state; `null` while no plugin has a panel there (or without `ui.mount`). */
+    /**
+     * The current state; `null` while no plugin has a panel there (or without
+     * `ui.mount`). With sidebar tabs it is the whole position's: shown,
+     * hidden and floating apply to all tabs, which {@link PanelSlot.panels}
+     * lists.
+     */
     readonly state: SlotState | null;
+    /**
+     * The position's panels in tab order: the sidebar's tabs, the bottom
+     * bar's one panel; `null` while there is none (as `state`), and from
+     * players without sidebar tabs (0.4.0 and older). Refreshed with `state`.
+     *
+     * @throws Never.
+     *
+     * @since 1.5.2
+     */
+    readonly panels: readonly SlotPanel[] | null;
     /**
      * Run code when the position's state changes.
      *
      * @remarks
      * Needs `events`: without it the listener runs only after this plugin's own
-     * changes. Called with `null` when the panel there is unmounted. Errors go
-     * to {@link Scope.onError}.
+     * changes. Called with `null` when the panel there is unmounted, and also
+     * when only the tabs changed ({@link PanelSlot.panels}: a panel added or
+     * removed, another tab current). Errors go to {@link Scope.onError}.
      *
      * @capability ui.mount and events
      *
@@ -1316,6 +1381,41 @@ export interface PanelSlot {
      * @since 1.0.0
      */
     toggle(): Promise<void>;
+    /**
+     * Make a panel's tab the current one, without showing or hiding the
+     * position.
+     *
+     * @remarks
+     * The sidebar holds the panels of several plugins as tabs (see
+     * {@link Panels.mount}); this switches which one it shows, like a click on
+     * its tab. To show this plugin's own panel, use {@link Panel.show}. The
+     * bottom bar has one panel: activating it changes nothing. Players
+     * without sidebar tabs (0.4.0 and older) ignore it.
+     *
+     * @capability ui.mount
+     *
+     * @param plugin - The manifest id of the plugin whose panel to show, one
+     *   of {@link PanelSlot.panels}.
+     * @returns Resolves once the layout has the new current tab, with `state`
+     *   refreshed.
+     *
+     * @throws `missing` (rejects) No panel is mounted at this position, or
+     *   none of `plugin`.
+     * @throws `unavailable` (rejects) The player runs without a user interface.
+     * @throws `capability` (rejects) The manifest does not declare `ui.mount`.
+     *
+     * @example A command that shows the playlist's tab
+     * ```ts
+     * plugin.commands.add({
+     *   id: "to-playlist",
+     *   title: "Show the playlist tab",
+     *   run: () => plugin.panels.sidebar.activate("vestra.playlist"),
+     * });
+     * ```
+     *
+     * @since 1.5.2
+     */
+    activate(plugin: string): Promise<void>;
 }
 /**
  * The sidebar position: a {@link PanelSlot} that can also float in a window
@@ -1330,8 +1430,17 @@ export interface PanelSlot {
  *
  * @capability ui.mount
  *
- * @example
- * {@includeCode ../../examples/core-ui/main.ts#sidebar}
+ * @example A "Detach sidebar" menu item
+ * ```ts
+ * const sidebar = plugin.panels.sidebar;
+ * plugin.commands.add({
+ *   id: "detach",
+ *   path: ["Tools", "Detach sidebar"],
+ *   checked: () => sidebar.state?.detached ?? false,
+ *   enabled: () => sidebar.state !== null,
+ *   run: () => sidebar.setDetached(!sidebar.state?.detached),
+ * });
+ * ```
  *
  * @since 1.0.0
  * @category UI
@@ -1400,14 +1509,25 @@ export interface Panel extends View, Disposable {
      *
      * @remarks
      * Mounts made while `activate` runs must succeed before the plugin is
-     * ready: a rejection fails activation. Later failures also go to
-     * {@link Scope.onError}.
+     * ready: a rejection fails activation, except `conflict` for a taken
+     * position (below), which the player (0.4.x after 0.4.0) and `TestHost`
+     * do not count: the plugin runs without its panel, its commands and keys
+     * work, and the player shows the refusal (an OSD message,
+     * {@link PluginInfo.warnings} and the text in {@link PluginInfo.error}).
+     * Later failures also go to {@link Scope.onError}.
+     *
+     * 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.
      *
      * @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. Also when another plugin's panel already occupies the
-     *   bottom bar or the sidebar.
-     * @throws `conflict` (rejects) Another plugin shows the backdrop.
+     *   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.
      * @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
@@ -1418,6 +1538,107 @@ export interface Panel extends View, Disposable {
      * @throws `capability` (rejects) The manifest does not declare `ui.mount`.
      */
     readonly ready: Promise<void>;
+    /**
+     * This panel's state: its position's, and whether its tab is the current
+     * one; `null` until {@link Panel.ready} resolved (and after `dispose`).
+     *
+     * @remarks
+     * Read when first used; with `events` it then follows every change (the
+     * user switching tabs, other plugins, the window size), without `events`
+     * only this plugin's own changes. A sidebar panel in a background tab
+     * has `active: false`, `effective: false` and `reason: "otherTab"`.
+     *
+     * @throws Never; `null` stands for "not mounted".
+     *
+     * @since 1.5.2
+     */
+    readonly state: PanelState | null;
+    /**
+     * Run code when this panel's state changes.
+     *
+     * @remarks
+     * Needs `events`: without it the listener runs only after this plugin's
+     * own changes. Called with `null` when the panel is unmounted. Errors go
+     * to {@link Scope.onError}.
+     *
+     * @capability ui.mount and events
+     *
+     * @param listener - Receives the new state.
+     * @returns A handle that removes the listener.
+     *
+     * @example Say when the user switched to another tab
+     * ```ts
+     * const panel = plugin.panels.mount("sidebar", "ui/list.slint", { title: "List" });
+     * panel.onChange((state) => {
+     *   if (state?.reason === "otherTab") console.error("list in a background tab");
+     * });
+     * ```
+     *
+     * @since 1.5.2
+     */
+    onChange(listener: (state: PanelState | null) => void): Disposable;
+    /**
+     * Show this panel: make its tab the current one and show its position.
+     *
+     * @remarks
+     * Sets the position's preference like {@link PanelSlot.setVisible}`(true)`
+     * (remembered; in fullscreen the sidebar overlay pops out). On players
+     * without sidebar tabs (0.4.0 and older) it is just that. Waits for
+     * {@link Panel.ready} first.
+     *
+     * @capability ui.mount
+     *
+     * @returns Resolves once the layout shows the panel's tab, with `state`
+     *   refreshed.
+     *
+     * @throws `invalid` (rejects) The panel is the backdrop, which the player
+     *   shows by itself.
+     * @throws `unavailable` (rejects) The player runs without a user interface.
+     * @throws The errors of {@link Panel.ready} (rejects) The mount failed.
+     *
+     * @example
+     * ```ts
+     * const list = plugin.panels.mount("sidebar", "ui/list.slint", { title: "List" });
+     * plugin.commands.add({ id: "show", title: "Show the list", run: () => list.show() });
+     * ```
+     *
+     * @since 1.5.2
+     */
+    show(): Promise<void>;
+    /**
+     * Show this panel, or hide its position when it is shown.
+     *
+     * @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"
+     * command checked by `state.preferred && state.active` matches it. Waits
+     * for {@link Panel.ready} first.
+     *
+     * @capability ui.mount
+     *
+     * @returns Resolves once the layout has changed, with `state` refreshed.
+     *
+     * @throws `invalid` (rejects) The panel is the backdrop.
+     * @throws `unavailable` (rejects) The player runs without a user interface.
+     * @throws The errors of {@link Panel.ready} (rejects) The mount failed.
+     *
+     * @example A toggle command for a sidebar panel (the playlist's F6)
+     * ```ts
+     * const list = plugin.panels.mount("sidebar", "ui/list.slint", { title: "List" });
+     * plugin.commands.add({
+     *   id: "list",
+     *   path: ["@screen", "List"],
+     *   bindings: ["F6"],
+     *   checked: () => (list.state?.preferred ?? false) && (list.state?.active ?? false),
+     *   run: () => list.toggle(),
+     * });
+     * ```
+     *
+     * @since 1.5.2
+     */
+    toggle(): Promise<void>;
     /**
      * Keep the panel on screen while the user works in it.
      *
@@ -1471,8 +1692,8 @@ export interface Panel extends View, Disposable {
      * @returns Resolves once the menu is open (not when the user picks).
      *
      * @throws `missing` (rejects) An item is not a command of this plugin.
-     * @throws `unavailable` (rejects) The panel is not on screen, or it is the
-     *   backdrop.
+     * @throws `unavailable` (rejects) The panel is not on screen (also: its
+     *   sidebar tab is not the current one), or it is the backdrop.
      * @throws `invalid` (rejects) No items, more than 32, or `at` is not
      *   finite.
      * @throws The errors of {@link Panel.ready} (rejects) The mount failed.
@@ -1714,12 +1935,59 @@ export type SettingsCategory = "general" | "playback" | "subtitles" | "video" |
  *
  * @capability ui.settings
  *
- * @example Two preferences on a page (examples/blur)
- * {@includeCode ../../examples/blur/main.ts#settings-page}
+ * @example Two preferences on a page, kept in a store
+ * ```ts
+ * const store = plugin.storage.json("blur", {
+ *   defaults: { restoreOnStart: false, messages: true },
+ * });
+ * const page = plugin.settings.page("ui/settings.slint", {
+ *   id: "blur",
+ *   category: "video",
+ *   title: "Blur",
+ * });
+ * page.bind(() => ({
+ *   restoreOnStart: store.value.restoreOnStart,
+ *   messages: store.value.messages,
+ * }));
+ * page.on("restoreToggled", (on: boolean) =>
+ *   store.save({ ...store.value, restoreOnStart: on }),
+ * );
+ * page.on("messagesToggled", (on: boolean) =>
+ *   store.save({ ...store.value, messages: on }),
+ * );
+ * ```
+ *
+ * `ui/settings.slint` exports the bridge global and the layout:
+ *
+ * ```slint
+ * import { CheckBox } from "std-widgets.slint";
+ * import { Theme } from "@vestra/theme.slint";
  *
- * `ui/settings.slint`:
+ * export global BlurPage {
+ *     in-out property <bool> restore-on-start;
+ *     in-out property <bool> messages: true;
+ *     callback restore-toggled(bool);
+ *     callback messages-toggled(bool);
+ * }
  *
- * {@includeCode ../../examples/blur/ui/settings.slint}
+ * export component BlurSettings inherits Rectangle {
+ *     VerticalLayout {
+ *         padding: Theme.dialog-padding;
+ *         spacing: 6px;
+ *         alignment: start;
+ *         CheckBox {
+ *             text: "Turn blur back on when the player starts";
+ *             checked <=> BlurPage.restore-on-start;
+ *             toggled => { BlurPage.restore-toggled(self.checked); }
+ *         }
+ *         CheckBox {
+ *             text: "Show on-screen messages";
+ *             checked <=> BlurPage.messages;
+ *             toggled => { BlurPage.messages-toggled(self.checked); }
+ *         }
+ *     }
+ * }
+ * ```
  *
  * @see {@link Settings.page}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
  * @since 1.0.0
@@ -1854,7 +2122,7 @@ export interface Settings {
      * @throws `capability` (rejects) The manifest does not declare
      *   `ui.settings`.
      *
-     * @example An "Options…" button in a tool window (examples/blur)
+     * @example An "Options…" button in a tool window
      * ```ts
      * const controls = plugin.windows.create("ui/window.slint");
      * controls.on("openOptions", () => plugin.settings.show("blur"));
@@ -1967,9 +2235,17 @@ export interface Panels {
      *   floats over the video and hides after 3 seconds without activity.
      * - `"sidebar"`: right of the video, the window's full height, as wide as the
      *   user drags it (at least 317). The user can detach it into a floating
-     *   window titled `title`.
+     *   window titled `title`. Several plugins may mount here (player 0.4.x
+     *   after 0.4.0): each panel is a tab, labelled `title` (else the plugin's
+     *   name), and the player draws a 31px tab strip above the current one
+     *   while there are two or more (with one panel, nothing changes).
+     *   Showing, hiding and detaching apply to the whole sidebar. If the
+     *   bridge global declares `in property <bool> tabbed`, the player sets
+     *   it to `true` while it draws the strip, so a panel with a tab strip of
+     *   its own can hide it. Panel coordinates (drops) start below the strip.
      * - `"backdrop"`: the whole video area, under the OSD, while there is no
-     *   video picture (see {@link Panels.backdrop}). One plugin at a time; it
+     *   video picture (see {@link Panels.backdrop}). One plugin at a time (as
+     *   for the bottom bar, another one's mount rejects with `conflict`); it
      *   takes no pointer or keyboard input. While it is mounted, the player does
      *   not show the cover art of audio files itself (from the next file
      *   opened on), so the plugin can draw it.
@@ -3051,8 +3327,14 @@ export interface OsdPanel extends Disposable {
  *
  * @capability ui.osd
  *
- * @example On-screen messages that the user can turn off (examples/blur)
- * {@includeCode ../../examples/blur/main.ts#osd}
+ * @example On-screen messages that the user can turn off
+ * ```ts
+ * const store = plugin.storage.json("prefs", { defaults: { messages: true } });
+ * const say = (text: string) => {
+ *   if (store.value.messages) void plugin.osd.show(text);
+ * };
+ * say("Blur on");
+ * ```
  *
  * @see {@link OsdPanel}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
  * @since 1.0.0
@@ -3729,6 +4011,30 @@ export interface PluginInfo {
      * the player has none. The path's layout is not part of the API.
      */
     dataDirectory: string | null;
+    /**
+     * What a running plugin was refused because another plugin holds it: a
+     * panel position (`slot-occupied`, with `slot`) or the next/previous
+     * sequence (`sequence-taken`). Neither fails activation; `error` has the
+     * same as text. Empty from players before 0.4.x (after 0.4.0).
+     * Always set by the SDK; optional so that code building `PluginInfo`
+     * values itself (tests) keeps compiling.
+     *
+     * @since 1.5.2
+     */
+    warnings?: readonly PluginWarning[];
+}
+/**
+ * One refusal in {@link PluginInfo.warnings}.
+ *
+ * @since 1.5.2
+ */
+export interface PluginWarning {
+    /** `"slot-occupied"` or `"sequence-taken"`; a newer player may add codes. */
+    code: string;
+    /** The panel position (`"bottom"`, `"sidebar"`, `"backdrop"`) for `slot-occupied`. */
+    slot?: string;
+    /** The manifest id of the plugin holding it (absent for a full sidebar). */
+    owner?: string;
 }
 /**
  * `plugin.packages`: the plugins the player knows. `list` and `onChange`

package/dist/plugin/ui.js

@@ -323,6 +323,7 @@ export function exported(directory, file, kind) {
 }
 class PanelHandle extends ViewBase {
     ready;
+    #slot;
     #mounted = false;
     #locks = { focused: false, dragging: false, popupOpen: false };
     #interaction;
@@ -330,6 +331,7 @@ class PanelHandle extends ViewBase {
         if (scope.runtime.views.has("$mount"))
             throw new Error("a plugin can mount only one panel");
         super(scope);
+        this.#slot = slot;
         const runtime = scope.runtime;
         runtime.views.set("$mount", (callback, args) => this.dispatch(callback, args));
         this.#interaction = new Latest((locks) => runtime.host.ui.interaction(locks));
@@ -364,6 +366,51 @@ class PanelHandle extends ViewBase {
     write(property, value) {
         return this.scope.runtime.host.ui.setMount(property, value);
     }
+    get state() {
+        const service = layoutOf(this.scope.runtime);
+        service.start();
+        return this.live()
+            ? panelState(service.state, this.#slot, this.scope.runtime.manifest.id)
+            : null;
+    }
+    onChange(listener) {
+        const scope = this.scope;
+        let last = JSON.stringify(this.state);
+        const watch = layoutOf(scope.runtime).watch(() => {
+            const state = this.state;
+            const next = JSON.stringify(state);
+            if (next === last)
+                return;
+            last = next;
+            scope.run(listener, state);
+        });
+        return scope.add({
+            dispose: async () => {
+                scope.forget(watch);
+                await watch.dispose();
+            },
+        });
+    }
+    async show() {
+        await this.ready;
+        if (this.#slot === "backdrop")
+            throw failure("invalid", "the player shows the backdrop by itself");
+        await layoutOf(this.scope.runtime).set(this.#slot, {
+            active: this.scope.runtime.manifest.id,
+            visible: true,
+        });
+    }
+    async toggle() {
+        await this.ready;
+        if (this.#slot === "backdrop")
+            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)
+            await layoutOf(this.scope.runtime).set(this.#slot, { visible: false });
+        else
+            await this.show();
+    }
     async showMenu(items, at) {
         await this.ready;
         await this.scope.runtime.host.ui.menu(items.map((item) => item?.id ?? null), at.x, at.y);
@@ -388,8 +435,38 @@ class PanelHandle extends ViewBase {
         this.#mounted = false;
         await this.release();
         this.scope.runtime.views.delete("$mount");
+        // Listeners of `onChange` hear `null`.
+        this.scope.runtime.invalidate();
+        await layoutOf(this.scope.runtime).refresh();
     }
 }
+/** One panel's view of its position (`Panel.state`). */
+function panelState(layout, slot, plugin) {
+    if (slot === "backdrop")
+        return (layout.backdrop && {
+            active: true,
+            preferred: true,
+            effective: layout.backdrop.effective,
+            reason: null,
+            detached: false,
+        });
+    const state = layout[slot];
+    if (!state)
+        return null;
+    // Players without tabs (no `panels`): the position holds this panel only.
+    const panels = layout.tabs[slot];
+    const own = panels?.find((panel) => panel.plugin === plugin);
+    if (panels && !own)
+        return null;
+    const active = own?.active ?? true;
+    return {
+        active,
+        preferred: state.preferred,
+        effective: state.effective && active,
+        reason: active ? state.reason : "otherTab",
+        detached: state.detached,
+    };
+}
 export const windows = (scope) => ({
     create: (file, options) => new WindowHandle(scope, file, options?.id ?? basename(file, extname(file))),
 });
@@ -400,7 +477,12 @@ export const windows = (scope) => ({
  */
 class LayoutService {
     #runtime;
-    state = { bottom: null, sidebar: null, backdrop: null };
+    state = {
+        bottom: null,
+        sidebar: null,
+        tabs: { bottom: null, sidebar: null },
+        backdrop: null,
+    };
     #listeners = new Set();
     #started = false;
     #reading = false;
@@ -444,9 +526,17 @@ class LayoutService {
                     reason: slot.reason,
                     detached: slot.detached,
                 };
+                const tabs = (slot) => slot?.panels
+                    ? Object.freeze(slot.panels.map((panel) => Object.freeze({
+                        plugin: panel.plugin,
+                        title: panel.title,
+                        active: panel.owner === slot.owner,
+                    })))
+                    : null;
                 const next = {
                     bottom: view(raw.bottom),
                     sidebar: view(raw.sidebar),
+                    tabs: { bottom: tabs(raw.bottom), sidebar: tabs(raw.sidebar) },
                     backdrop: raw.backdrop
                         ? Object.freeze({ effective: raw.backdrop.effective === true })
                         : null,
@@ -477,10 +567,15 @@ function slot(scope, name) {
             service().start();
             return service().state[name];
         },
+        get panels() {
+            service().start();
+            return service().state.tabs[name];
+        },
         onChange(listener) {
-            let last = JSON.stringify(service().state[name]);
+            const seen = (layout) => JSON.stringify([layout[name], layout.tabs[name]]);
+            let last = seen(service().state);
             const watch = service().watch((layout) => {
-                const next = JSON.stringify(layout[name]);
+                const next = seen(layout);
                 if (next === last)
                     return;
                 last = next;
@@ -500,6 +595,7 @@ function slot(scope, name) {
             await service().set(name, { visible: !(current?.preferred ?? true) });
         },
         setDetached: (detached) => service().set(name, { detached }),
+        activate: (plugin) => service().set(name, { active: plugin }),
     };
 }
 function backdrop(scope) {

package/dist/wire.d.ts

@@ -112,6 +112,12 @@ export interface PackageInfo {
     builtin?: boolean;
     source?: WireSource | null;
     dataDirectory?: string | null;
+    /** What the plugin was refused because another plugin holds it (player 0.4.x, after 0.4.0). */
+    warnings?: {
+        code: string;
+        slot?: string;
+        owner?: string;
+    }[];
 }
 /** Where an installed package came from (`packages.install` `source`). */
 export type WireSource = {
@@ -182,13 +188,24 @@ export interface LayoutBackdrop {
     owner: number;
     effective: boolean;
 }
+/** One panel of a position, in tab order (`LayoutSlot.panels`). */
+export interface LayoutPanel {
+    owner: number;
+    /** The manifest id of the plugin that mounted it. */
+    plugin: string;
+    /** The tab label: the mount's `title`, else the plugin's name. */
+    title: string;
+}
 /** One position (bottom bar or sidebar) as `layout.state` reports it. */
 export interface LayoutSlot {
+    /** The current tab's panel (the only panel of the bottom bar). */
     owner: number;
     preferred: boolean;
     effective: boolean;
     reason: "userHidden" | "space" | "fullscreen" | "idle" | null;
     detached: boolean;
+    /** The position's panels in tab order; absent from players without sidebar tabs (0.4.0 and older). */
+    panels?: LayoutPanel[];
 }
 export interface PlaybackStats {
     backend: string;
@@ -470,6 +487,8 @@ export declare function createWire(transport: Transport): {
             slot: "bottom" | "sidebar";
             visible?: boolean;
             detached?: boolean;
+            /** The plugin id of the panel whose tab becomes the current one. */
+            active?: string;
         }) => Promise<void>;
     };
     events: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {