@vestra-player/sdk 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 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"`.
+
+- **`ThemeId` gains `"vestra-light"`**, a light palette whose video area stays dark. `plugin.appearance.set("vestra-light")` switches every view; `TestHost` accepts it like the player. A player older than 0.4.0 answers it with `vestra` (an id it does not have).
+- **New colours for `vestra`.** The palette is now Aurora, drawn from the logo's full spectrum: magenta accent (`#f72aa6`), cyan for what is playing (`Theme.playing`, `#2bb6ff`, violet before), `Theme.accent-fill` from amber through magenta and violet to cyan, and a visible `Theme.line` (`#2b2734`; it was near-black). Token names are unchanged; code that reads `Theme` follows.
+- **Rounder corners**: `Theme.radius-control` 4px (was 3px), `Theme.radius-panel` 8px (was 6px). Sizes are otherwise unchanged.
+- **`@vestra/icons.slint`** (new library file, `slint/vestra/icons.slint`): `Icon { name: "play"; color: Theme.text; }` draws one icon of the player's own set (round-capped 1.5px lines), and `Icons.commands(name)` / `box-width` / `box-height` / `line` give its path data. The names are listed in **Windows, panels, settings pages, dialogs and the OSD**.
+- **`@vestra/widgets.slint`**: the bar slider's thumb is a white core in a 2px accent ring; the panel slider's track is `Theme.line`; stroked icon buttons use round caps and joins; tooltips have rounded corners. Geometry and API are unchanged.
+- **std-widgets in a light palette**: the player still compiles plugin files with `fluent-dark` and switches the std-widgets colour scheme (`Palette.color-scheme`) to light for `vestra-light`, so `CheckBox`, `ComboBox`, `LineEdit`, `ScrollView` and the other std-widgets controls follow. The player's palette file (`slint/palette.slint`, not part of the library) now imports `std-widgets.slint` for that.
+
+## 1.4.1
+
+Documentation only; no code or type changes.
+
+- **Built-in menus keep their place** (player 0.3.0). `CommandOptions` and `CommandOptions.order` document the player's menu rule: the seven built-in top-level menus (`@open` … `@settings`) sit at fixed orders (Open 110, Playback 200, Subtitles 300, Video 400, Audio 500, Screen 710, Settings 830), whether a path names them by id or by title, so a plugin's item never moves them. Directly inside a built-in menu, `order` 0 (the default) sorts after every other order, so an item without `order` goes at the end. Players before 0.3.0 move the whole menu to the top for such an item; give it an order in the menu's range there.
+- The Blur walkthrough explains `order` inside the Video menu accordingly.
+
 ## 1.4.0
 
 **One palette.** `ThemeId` is now `"vestra"` only: the second palette that earlier versions listed is gone from the player. This is a minor version although a type narrows, because the only plugins it affects compare `plugin.appearance.theme` with, or `set` the removed id:

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,34 +60,36 @@ 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) |
 
 Minor releases only add backwards-compatible API; a breaking change gets a new `apiVersion` and a new major version. `@vestra-player/sdk/runtime` is for the player only and not covered by semver.
 

package/dist/commands.d.ts

@@ -54,7 +54,7 @@ export type CommandDeclaration = {
     title: string;
     /** Complete primary menu path INCLUDING its leaf; empty = not in the main menu. */
     path: string[];
-    /** Sibling order, ascending; a submenu takes its first command's order. */
+    /** Sibling order, ascending; a submenu takes its first command's order (a built-in menu keeps a fixed one). */
     order: number;
     /** Separator label: adjacent siblings of different groups get a line. */
     group: string;

package/dist/plugin/appearance.js

@@ -2,7 +2,7 @@
 import { failure } from "./runtime.js";
 import { windowOf } from "./window.js";
 /** The palettes this SDK knows, the default first. */
-export const THEMES = ["vestra"];
+export const THEMES = ["vestra", "vestra-light"];
 /**
  * One per plugin: the value comes with the `window.state` read before
  * activation; with `events`, `appearance.changed` keeps it current once

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/types.d.ts

@@ -376,6 +376,21 @@ export type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "sc
  * ranges: `open` 100–199, `domain` 200–699 (playback, subtitles, video,
  * audio…), `screen` 700–799, `windows` 800–899, `exit` 900–999.
  *
+ * Built-in menus keep their place. The seven built-in top-level menus
+ * ({@link MenuId}) sit at fixed orders, whatever is inside them: Open 110,
+ * Playback 200, Subtitles 300, Video 400, Audio 500, Screen 710, Settings
+ * 830 (player 0.3.0). This holds whether the path names the menu by id
+ * (`["@video", "Blur"]`) or by its title (`["视频", "Blur"]`), so a plugin's
+ * item never moves the player's menu. Directly inside a built-in menu,
+ * `order` 0 (the default) sorts after every other order: an item without
+ * `order` goes at the end, after the player's own items (which all use 100
+ * or more). Give a positive order to sit between them (the player's orders
+ * are listed in its menu table, doc/product/menus.md), or a negative one to
+ * come first. Deeper levels (a plugin's own submenu) have no such rule.
+ * Players before 0.3.0 place every submenu at its smallest order, so there
+ * an item without `order` moves the whole menu to the top; to avoid that,
+ * give it an order in the menu's range (Video: 400–499).
+ *
  * {@link Commands.add} throws `invalid` synchronously for a bad path,
  * order, group or binding. The same path registered twice, or a path that
  * is both an item and a submenu, fails with `conflict` (through `ready`).
@@ -406,8 +421,10 @@ export interface CommandOptions {
     title?: string;
     /**
      * Sibling order in the menu, ascending (integer, default 0). A submenu sits
-     * where its first command sits. Equal orders: plugin id, then declaration order.
-     * Range ±1,000,000.
+     * where its first command sits, except a built-in menu, which keeps its
+     * fixed place. Directly inside a built-in menu, 0 (the default) sorts last.
+     * Equal orders: plugin id, then declaration order. Range ±1,000,000. See
+     * {@link CommandOptions} for the menu order rules.
      */
     order?: number;
     /** Separator label: a line is drawn between adjacent items of different groups. Default `"domain"`. */
@@ -1212,8 +1229,17 @@ 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
@@ -1313,8 +1339,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
@@ -1562,19 +1597,20 @@ export interface Drops {
     provide(handler: DropHandler): Disposable;
 }
 /**
- * The player's palettes. Today there is one, `vestra` (the default); a later
- * version may add more (a light palette, for example), so read colours from
- * `Theme` instead of branching on the id.
+ * The player's palettes: `vestra`, the dark default, and `vestra-light`
+ * (player 0.4.0, SDK 1.5.0), a light palette whose video area stays dark.
+ * Both draw on the logo's colours. Read colours from `Theme` instead of
+ * branching on the id: a later version may add palettes.
  *
  * @remarks
- * SDK 1.4.0 removed a second palette that earlier versions listed. The player
- * treats an id it does not have as `vestra`, so plugins built with an older
- * SDK that still ask for it keep working.
+ * The player treats an id it does not have as `vestra`: plugins built with an
+ * older SDK that still ask for a palette removed in SDK 1.4.0 keep working,
+ * and a player older than 0.4.0 answers `vestra-light` with `vestra`.
  *
  * @since 1.0.0
  * @category UI
  */
-export type ThemeId = "vestra";
+export type ThemeId = "vestra" | "vestra-light";
 /**
  * The player's palette, which every view uses. `plugin.appearance`.
  *
@@ -1584,7 +1620,9 @@ export type ThemeId = "vestra";
  * and again when the palette changes. Slint code that reads its colours from
  * `Theme` (`import { Theme } from "@vestra/theme.slint"`) follows it with no
  * plugin code; hard-coded colours do not. Only colours change: corner radii,
- * font sizes and control sizes are the same in every palette.
+ * font sizes and control sizes are the same in every palette. A light palette
+ * also switches the std-widgets controls (`std-widgets.slint`) to their light
+ * colours, and keeps the video area dark.
  *
  * The player saves the choice; it stays after the plugin that set it stops.
  * Tell the user about a change yourself (for example with
@@ -1593,14 +1631,14 @@ export type ThemeId = "vestra";
  * @capability None to read `theme`; `events` to follow changes; `ui.theme`
  *   to change it.
  *
- * @example A menu item that selects the palette
+ * @example A menu item that selects the light palette
  * ```ts
  * plugin.commands.add({
- *   id: "vestra-colours",
- *   path: ["@settings", "Vestra colours"],
+ *   id: "light-colours",
+ *   path: ["@settings", "Light colours"],
  *   radio: true,
- *   checked: () => plugin.appearance.theme === "vestra",
- *   run: () => plugin.appearance.set("vestra"),
+ *   checked: () => plugin.appearance.theme === "vestra-light",
+ *   run: () => plugin.appearance.set("vestra-light"),
  * });
  * ```
  *
@@ -1657,7 +1695,7 @@ export interface Appearance {
      *
      * @example
      * ```ts
-     * await plugin.appearance.set("vestra");
+     * await plugin.appearance.set("vestra-light");
      * ```
      *
      * @since 1.0.0
@@ -1694,12 +1732,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:
  *
- * `ui/settings.slint`:
+ * ```slint
+ * import { CheckBox } from "std-widgets.slint";
+ * import { Theme } from "@vestra/theme.slint";
  *
- * {@includeCode ../../examples/blur/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);
+ * }
+ *
+ * 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
@@ -1834,7 +1919,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"));
@@ -3031,8 +3116,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

package/package.json

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

package/slint/palette.slint

@@ -1,32 +1,42 @@
 // The player's colour palette (R-H6) and per-system fonts. Not part of the
 // plugin library: the player sets these `in` properties on every view;
 // `Theme` in @vestra/theme.slint reads them as `out` properties. Defaults:
-// Vestra colours, the macOS fonts.
+// the Aurora colours of the `vestra` palette, the macOS fonts.
+import { Palette } from "std-widgets.slint";
+
 export global VestraPalette {
-    in property <color> bg-bar: #17141c;
-    in property <color> bg-video: #0b0a0f;
-    in property <color> bg-list: #1c1922;
-    in property <color> bg-panel: #221e29;
-    in property <color> line: #07060a;
-    in property <color> hover-bg: #2a2533;
-    in property <color> press-bg: #120f16;
-    in property <color> selected-bg: #2f2938;
-    in property <color> text: #f2eff7;
-    in property <color> text-dim: #8a8496;
-    in property <color> text-list: #b8b2c4;
-    in property <color> text-played: #6f6a7a;
-    in property <color> accent: #fa139c;
-    in property <color> accent-press: #c40f7a;
-    in property <color> accent-disabled: #5c1a42;
-    in property <color> icon-disabled: #3a3542;
-    in property <color> playing: #a24bff;
-    in property <color> button-bg: #322c3b;
-    in property <color> button-hover: #3d3648;
-    in property <color> button-press: #26212e;
-    in property <color> button-disabled: #1d1a23;
+    in property <color> bg-bar: #16141c;
+    in property <color> bg-video: #0a090e;
+    in property <color> bg-list: #1a1821;
+    in property <color> bg-panel: #201d28;
+    in property <color> line: #2b2734;
+    in property <color> hover-bg: #28232f;
+    in property <color> press-bg: #110f16;
+    in property <color> selected-bg: #2f2840;
+    in property <color> text: #f5f3fa;
+    in property <color> text-dim: #8e88a0;
+    in property <color> text-list: #bdb8cb;
+    in property <color> text-played: #6e6980;
+    in property <color> accent: #f72aa6;
+    in property <color> accent-press: #c41a83;
+    in property <color> accent-disabled: #5a1d48;
+    in property <color> icon-disabled: #3b3646;
+    in property <color> playing: #2bb6ff;
+    in property <color> button-bg: #2f2a3b;
+    in property <color> button-hover: #3a3448;
+    in property <color> button-press: #25202e;
+    in property <color> button-disabled: #1b1922;
     // Errors and destructive actions (failed status, delete).
-    in property <color> danger: #ff5a4a;
+    in property <color> danger: #ff5a5f;
     // The system's monospace family (platform::monospace_font).
     in property <string> font-mono: "Menlo";
-    in property <brush> accent-fill: @linear-gradient(90deg, #fdb506 0%, #fc6f3b 25%, #fa139c 60%, #911efc 100%);
+    // Each palette's progress gradient, logo amber → magenta → violet → cyan.
+    // The player copies one into `accent-fill` (Slint's Rust API cannot
+    // build gradients).
+    out property <brush> fill-vestra: @linear-gradient(90deg, #fcc402 0%, #fb5a35 20%, #fa0aa8 45%, #7a0afa 72%, #10a8fc 100%);
+    out property <brush> fill-vestra-light: @linear-gradient(90deg, #f5a700 0%, #f0442f 20%, #e0089a 45%, #6a08e8 72%, #0a95e6 100%);
+    in property <brush> accent-fill: self.fill-vestra;
+    // The std-widgets (fluent) controls follow the palette: the player sets
+    // `light` for a light palette.
+    in-out property <ColorScheme> color-scheme <=> Palette.color-scheme;
 }

package/slint/vestra/icons.slint

@@ -0,0 +1,99 @@
+// The V-Line icon set (doc/product/ui-spec.md §2.4): round-capped, round-joined
+// lines, 1.5px (1.25px for the small glyphs), never filled. The V of the
+// logo recurs: « » for back and forward, ∧ ∨ for moving rows, a small V for
+// every menu, list and scroll arrow.
+//   import { Icon } from "@vestra/icons.slint";
+//   Icon { name: "play"; color: Theme.text; }
+// Each icon is drawn in its own box (`Icons.box-width` × `Icons.box-height`),
+// which is also the Icon's default size; an unknown name draws nothing.
+import { Theme } from "theme.slint";
+
+export global Icons {
+    // Path data in the icon's box.
+    public pure function commands(name: string) -> string {
+        if name == "play" { return "M 2.2 2.0 L 10.9 7 L 2.2 12.0 Z"; }
+        if name == "pause" { return "M 1.75 1.75 H 4.5 V 12.25 H 1.75 Z M 7.5 1.75 H 10.25 V 12.25 H 7.5 Z"; }
+        if name == "stop" { return "M 3.6 1.5 H 8.4 Q 10.5 1.5 10.5 3.6 V 8.4 Q 10.5 10.5 8.4 10.5 H 3.6 Q 1.5 10.5 1.5 8.4 V 3.6 Q 1.5 1.5 3.6 1.5 Z"; }
+        if name == "back" { return "M 6.5 1.25 L 2.5 5 L 6.5 8.75 M 12 1.25 L 8 5 L 12 8.75"; }
+        if name == "forward" { return "M 2 1.25 L 6 5 L 2 8.75 M 7.5 1.25 L 11.5 5 L 7.5 8.75"; }
+        if name == "open" { return "M 1.5 3.2 Q 1.5 1.5 3.2 1.5 H 5.2 L 6.8 3.2 H 10.8 Q 12.5 3.2 12.5 4.9 V 8.8 Q 12.5 10.5 10.8 10.5 H 3.2 Q 1.5 10.5 1.5 8.8 Z"; }
+        if name == "volume" { return "M 1 3.6 H 3 L 6 1.2 V 8.8 L 3 6.4 H 1 Z M 8.6 3.4 Q 9.7 5 8.6 6.6 M 10.6 1.6 Q 12.6 5 10.6 8.4"; }
+        if name == "mute" { return "M 1 3.6 H 3 L 6 1.2 V 8.8 L 3 6.4 H 1 Z M 8.8 3.4 L 12 6.6 M 12 3.4 L 8.8 6.6"; }
+        if name == "playlist" { return "M 1.25 1.5 H 11.75 M 1.25 5 H 11.75 M 1.25 8.5 H 6.5 M 9.2 7.2 L 10.5 8.5 L 11.8 7.2"; }
+        if name == "detach" { return "M 5.5 1.5 H 3.3 Q 1.5 1.5 1.5 3.3 V 8.7 Q 1.5 10.5 3.3 10.5 H 8.7 Q 10.5 10.5 10.5 8.7 V 6.5 M 8.5 1.5 H 12.5 V 5.5 M 12.5 1.5 L 6.5 7.5"; }
+        if name == "attach" { return "M 5.5 1.5 H 3.3 Q 1.5 1.5 1.5 3.3 V 8.7 Q 1.5 10.5 3.3 10.5 H 8.7 Q 10.5 10.5 10.5 8.7 V 6.5 M 12.5 1.5 L 7 7 M 7 3.5 V 7 H 10.5"; }
+        if name == "close" { return "M 3.5 3 L 10.5 10 M 10.5 3 L 3.5 10"; }
+        if name == "failed" { return "M 5 1.3 L 9.1 8.7 H 0.9 Z M 5 4.1 V 5.8 M 5 7.3 V 7.35"; }
+        if name == "move-top" { return "M 2.5 1.75 H 11.5 M 3 9.75 L 7 5.75 L 11 9.75"; }
+        if name == "move-up" { return "M 3 8 L 7 4 L 11 8"; }
+        if name == "move-down" { return "M 3 4 L 7 8 L 11 4"; }
+        if name == "move-bottom" { return "M 3 2.25 L 7 6.25 L 11 2.25 M 2.5 10.25 H 11.5"; }
+        if name == "search" { return "M 9 5.25 A 3.75 3.75 0 1 1 1.5 5.25 A 3.75 3.75 0 1 1 9 5.25 Z M 8 8 L 11.25 10.75"; }
+        if name == "chapter" { return "M 2.5 11 V 1.2 M 2.5 1.6 H 9.6 L 7.9 4.1 L 9.6 6.6 H 2.5"; }
+        if name == "bookmark" { return "M 3.2 1.2 H 8.8 V 10.6 L 6 8.3 L 3.2 10.6 Z"; }
+        if name == "check-task" { return "M 2.75 5.75 L 4.75 7.75 L 8.25 3.25"; }
+        if name == "check-box" { return "M 1.5 4.75 L 3.6 6.75 L 7.5 2.25"; }
+        if name == "menu-check" { return "M 4 7.25 L 6.25 9.5 L 10 4.75"; }
+        if name == "submenu" { return "M 1.25 1.25 L 3.75 4 L 1.25 6.75"; }
+        if name == "scroll-up" { return "M 1.25 3.75 L 4 1.25 L 6.75 3.75"; }
+        if name == "scroll-down" { return "M 1.25 1.25 L 4 3.75 L 6.75 1.25"; }
+        if name == "caret-down" { return "M 1.25 1.25 L 4 3.75 L 6.75 1.25"; }
+        if name == "sort-asc" { return "M 1 3.25 L 3.5 0.75 L 6 3.25"; }
+        if name == "sort-desc" { return "M 1 0.75 L 3.5 3.25 L 6 0.75"; }
+        if name == "tag-remove" { return "M 1.5 1.5 L 5.5 5.5 M 5.5 1.5 L 1.5 5.5"; }
+        if name == "preview-play" { return "M 1.5 1.3 L 6.9 4.5 L 1.5 7.7 Z"; }
+        if name == "add" { return "M 5 1.5 V 8.5 M 1.5 5 H 8.5"; }
+        if name == "remove" { return "M 1.5 5 H 8.5"; }
+        if name == "sort" { return "M 3 1.5 V 8.5 M 1.2 6.7 L 3 8.5 L 4.8 6.7 M 7 8.5 V 1.5 M 5.2 3.3 L 7 1.5 L 8.8 3.3"; }
+        return "";
+    }
+    // Line width.
+    public pure function line(name: string) -> length {
+        if name == "failed" || name == "chapter" || name == "bookmark" || name == "submenu" || name == "scroll-up" || name == "scroll-down" || name == "caret-down" || name == "tag-remove" || name == "preview-play" { return 1.25px; }
+        if name == "sort-asc" || name == "sort-desc" { return 1.1px; }
+        return 1.5px;
+    }
+    // The box the commands are drawn in.
+    public pure function box-width(name: string) -> length {
+        if name == "play" || name == "pause" || name == "stop" || name == "chapter" || name == "bookmark" { return 12px; }
+        if name == "failed" || name == "add" || name == "remove" || name == "sort" { return 10px; }
+        if name == "scroll-up" || name == "scroll-down" || name == "caret-down" || name == "preview-play" { return 8px; }
+        if name == "volume" || name == "mute" || name == "playlist" { return 13px; }
+        if name == "sort-asc" || name == "sort-desc" || name == "tag-remove" { return 7px; }
+        if name == "check-task" { return 11px; }
+        if name == "check-box" { return 9px; }
+        if name == "submenu" { return 5px; }
+        return 14px;
+    }
+    public pure function box-height(name: string) -> length {
+        if name == "back" || name == "forward" || name == "volume" || name == "mute" || name == "playlist" || name == "failed" || name == "add" || name == "remove" || name == "sort" { return 10px; }
+        if name == "play" || name == "pause" || name == "menu-check" { return 14px; }
+        if name == "scroll-up" || name == "scroll-down" || name == "caret-down" { return 5px; }
+        if name == "check-box" || name == "preview-play" { return 9px; }
+        if name == "sort-asc" || name == "sort-desc" { return 4px; }
+        if name == "close" { return 13px; }
+        if name == "check-task" { return 11px; }
+        if name == "submenu" { return 8px; }
+        if name == "tag-remove" { return 7px; }
+        return 12px;
+    }
+}
+
+// One icon, stroked in `color`; scaled when the caller sets another size.
+export component Icon {
+    in property <string> name;
+    in property <brush> color: Theme.text;
+    width: Icons.box-width(root.name);
+    height: Icons.box-height(root.name);
+    Path {
+        width: 100%;
+        height: 100%;
+        viewbox-width: Icons.box-width(root.name) / 1px;
+        viewbox-height: Icons.box-height(root.name) / 1px;
+        commands: Icons.commands(root.name);
+        stroke: root.color;
+        stroke-width: Icons.line(root.name);
+        stroke-line-cap: round;
+        stroke-line-join: round;
+    }
+}

package/slint/vestra/markdown.slint

@@ -6,6 +6,7 @@
 // open (usually `plugin.system.openUrl`).
 import { ScrollView } from "std-widgets.slint";
 import { Theme } from "theme.slint";
+import { Icon } from "icons.slint";
 
 // One table row (cells are plain text).
 export struct MarkdownRow {
@@ -86,18 +87,15 @@ component MarkdownBlockView {
                         y: 3px;
                         width: 11px;
                         height: 11px;
-                        border-width: 1px;
-                        border-radius: 2px;
+                        border-width: block.task == 2 ? 0px : 1px;
+                        border-radius: 3px;
                         border-color: Theme.text-dim;
                         background: block.task == 2 ? Theme.accent : transparent;
-                        if block.task == 2: Path {
+                        if block.task == 2: Icon {
                             width: 100%;
                             height: 100%;
-                            viewbox-width: 11;
-                            viewbox-height: 11;
-                            commands: "M 2.5 5.5 L 4.5 7.5 L 8.5 3";
-                            stroke: Theme.text;
-                            stroke-width: 1.5px;
+                            name: "check-task";
+                            color: #ffffff;
                         }
                     }
                 }

package/slint/vestra/theme.slint

@@ -1,7 +1,8 @@
 // Vestra theme tokens (doc/product/ui-spec.md §2.1–2.3). Import from any
 // plugin or host Slint file:  import { Theme } from "@vestra/theme.slint";
-// Colours follow the player's palette (R-H6: Vestra, set on every
-// view through ../palette.slint, which is not part of this library). They are
+// Colours follow the player's palette (R-H6: `vestra`, the dark default, or
+// `vestra-light`, set on every view through ../palette.slint, which is not
+// part of this library). They are
 // `out` properties: Slint code reads them but cannot assign them. So is
 // font-mono (set per system). Corner radii, font sizes and control sizes
 // stay constants.
@@ -9,8 +10,10 @@
 import { VestraPalette } from "../palette.slint";
 
 export global Theme {
-    // Colours: Vestra identity drawn from the logo (amber → magenta → violet on a
-    // violet-tinted near-black). Sizes below are the player's control geometry
+    // Colours: the Aurora palette drawn from the logo's full spectrum (magenta
+    // accent, cyan for what is playing, amber → magenta → violet → cyan fills;
+    // violet-tinted near-black, or near-white in vestra-light, whose video area
+    // stays dark). Sizes below are the player's control geometry
     // (doc/product/ui-spec.md §2.3), the same whatever the palette.
     out property <color> bg-bar: VestraPalette.bg-bar;
     out property <color> bg-video: VestraPalette.bg-video;
@@ -35,11 +38,12 @@ export global Theme {
     out property <color> button-disabled: VestraPalette.button-disabled;
     // Errors and destructive actions: a failed status line, a Delete button.
     out property <color> danger: VestraPalette.danger;
-    // Brand gradient for "progress" fills (seek bar, volume, sliders).
+    // Brand gradient for "progress" fills (seek bar, volume, sliders, accents).
     out property <brush> accent-fill: VestraPalette.accent-fill;
-    // Soft corners echo the logo.
-    out property <length> radius-control: 3px;
-    out property <length> radius-panel: 6px;
+    // Soft corners echo the logo: controls, menu rows and hover plates use
+    // radius-control; menus, panels and the OSD radius-panel.
+    out property <length> radius-control: 4px;
+    out property <length> radius-panel: 8px;
     // §2.2 fonts. No default family: every window uses the system UI font,
     // and Slint falls back per character for scripts a font lacks (CJK in
     // font-mono included). font-mono is the system's own monospace family,

package/slint/vestra/widgets.slint

@@ -1,6 +1,7 @@
 // Compact controls built on the Vestra theme (core-ui-design.md §2.1):
 //   import { Button, Slider, ToolTipArea, UrlInputRow } from "@vestra/widgets.slint";
-// Other controls come from std-widgets, which the host compiles as fluent-dark.
+// Icons: @vestra/icons.slint. Other controls come from std-widgets, which the
+// host compiles as fluent-dark and switches to light for a light palette.
 import { TextEdit } from "std-widgets.slint";
 import { Theme } from "theme.slint";
 
@@ -49,6 +50,7 @@ export component ToolTipArea {
             background: Theme.bg-panel;
             border-color: Theme.line;
             border-width: 1px;
+            border-radius: Theme.radius-control;
             HorizontalLayout {
                 padding-left: 5px; padding-right: 5px; padding-top: 2px; padding-bottom: 2px;
                 Text { text: root.text; color: Theme.text; font-size: Theme.font-body; }
@@ -59,7 +61,8 @@ export component ToolTipArea {
 
 // Dialog button: text (21px, or 18px when `small`), or an icon button when
 // `text` is empty and `icon` holds Path data drawn in an icon-width × icon-height
-// viewbox (filled, or 1.5px lines when `stroked`). The caller sizes icon buttons.
+// viewbox (filled, or 1.5px round-capped lines when `stroked`, as the
+// @vestra/icons.slint set). The caller sizes icon buttons.
 export component Button {
     in property <string> text;
     in property <string> icon;
@@ -112,6 +115,8 @@ export component Button {
         fill: root.stroked ? transparent : root.tint;
         stroke: root.stroked ? root.tint : transparent;
         stroke-width: root.stroked ? 1.5px : 0px;
+        stroke-line-cap: round;
+        stroke-line-join: round;
     }
     touch := TouchArea {
         enabled: root.enabled;
@@ -119,8 +124,9 @@ export component Button {
     }
 }
 
-// 2px line slider. Bar style (default): 8px round thumb, accent fill.
-// Panel style (`panel: true`): 14×12 thumb, blue fill on a dark track.
+// 2px line slider. Bar style (default): 8px round thumb, a white core in a
+// 2px accent ring, gradient fill. Panel style (`panel: true`): 14×12 thumb,
+// gradient fill. The track is `Theme.line` in both.
 export component Slider {
     in-out property <float> value;
     in property <float> minimum: 0;
@@ -146,7 +152,8 @@ export component Slider {
     Rectangle {
         y: (parent.height - 2px) / 2;
         height: 2px;
-        background: root.panel ? Theme.bg-bar : Theme.line;
+        border-radius: 1px;
+        background: Theme.line;
     }
     Rectangle {
         y: (parent.height - 2px) / 2;
@@ -162,10 +169,9 @@ export component Slider {
         width: root.thumb-width;
         height: root.thumb-height;
         border-radius: root.panel ? Theme.radius-control : self.height / 2;
-        background: !root.enabled ? Theme.icon-disabled
-            : root.panel ? Theme.text
-            : touch.pressed ? Theme.accent-press
-            : touch.has-hover ? Theme.accent : Theme.text;
+        background: !root.enabled ? Theme.icon-disabled : root.panel ? Theme.text : #ffffff;
+        border-width: root.panel || !root.enabled ? 0px : 2px;
+        border-color: touch.pressed ? Theme.accent-press : Theme.accent;
     }
     touch := TouchArea {
         enabled: root.enabled;