@vestra-player/sdk 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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"`.

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/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

@@ -1229,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
@@ -1330,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
@@ -1714,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
@@ -1854,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"));
@@ -3051,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.5.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": {