@vestra-player/sdk 1.5.30 → 1.5.31

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.5.31
+
+**Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Only documentation, its checks and the generated `llms-full.txt` change.
+
+- **The Commands, Playback and Services categories reach the full reference standard** (they are now in `STRICT_CATEGORIES`, so CI keeps them complete): `Commands`, `Command`, `Host` and their option types; `Player`, `Media`, `Scrub`, `Stream` and the playback state and stream types; `Storage`, `JsonStore`, `SessionStorage`, `Secrets`, `Clipboard`, `System`, `Tools`, `Power`. Every method has an example (what it does and how it works), `@capability`, `@since` and a `@throws` per error code it can reject with, checked against the SDK and the player's source; every type has `@category`, so the API reference lists them under their category instead of "Other". Methods with an explained example: 75 of 191 → 121.
+- Error codes the reference now names, from the player's source: a control while nothing is open is `invalid` (`close` is not: closing with nothing open just succeeds); `setRate` takes 0.05–10 (the player's own keys stay within 0.25–4); `setOutput`'s volume outside 0–200 is `invalid`; `Stream.stop` rejects only when closing the source fails, and releases the stream either way.
+- **Corrections from the review against the player's source.** `stale` means any change of the source since the state a call is based on: another file or a close, but also any pause, seek or speed change by the user or another plugin. A second sequence provider is refused with `conflict` (`sequence-taken`) without failing activation, and the built-in playlist registers first. `VESTRA_FFMPEG` / `VESTRA_FFPROBE` replace the `PATH` search instead of coming before it. More `@throws`: `capability` for `Secrets` and `Clipboard`; for a generated stream `busy` and `unsupported` for `seek` and `setRate`, `busy` for `setPaused` and `unsupported` for `restart`; `replaced`, `busy` and the resolver failures (`backend`, `unsupported`, `unavailable`) for `open`; `capability` for `Command.ready`; `aborted` for `openStream`; `stale` and `unsupported` for `Scrub.seek`; `disabled` and `unsupported` (players before 0.5.5) for session storage; `failed` and `timeout` (macOS) for `System`. *Store a plugin's data* no longer promises that a quit right after `save` loses nothing (a stopping plugin gets about 300 ms).
+- New how-to guides: *Control playback* (reading and following the state, `stale` and `ifCurrent`, `Media`, core actions, Next and Previous) and *Store a plugin's data* (settings files, session values, secrets, your own files).
+- `doc-lint`: `--list explained` lists the methods without an explained example; its summary line no longer says "Not enforced yet" (every example has been enforced since 1.5.30).
+- Comments and docs name the player's host files at their new places (`src/host/src/packages/manifest.rs`, `ui/ui_image.rs`, `ui/ui_values.rs`, `playback/effects.rs`, `ui/theme.rs`).
+
 ## 1.5.30
 
 **Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Only documentation, its checks and the generated `llms-full.txt` change.

package/dist/manifest.js

@@ -1,6 +1,6 @@
 /**
  * The manifest rules `vestra-plugin check` applies; the same table as the
- * player's `host/src/manifest.rs` (the player's tests compare the limits).
+ * player's `src/host/src/packages/manifest.rs` (the player's tests compare the limits).
  * Paths in the manifest are checked against the plugin directory.
  */
 import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";

package/dist/plugin/services.d.ts

@@ -69,7 +69,8 @@ export declare function system(scope: ScopeImpl): System;
  * too long. Values are 1–1024 bytes counted in UTF-8, so the check uses
  * `Buffer.byteLength`; `secrets.set` would refuse other values with
  * `invalid`. The store itself can still refuse (`unsupported` without a
- * system store, `unavailable` or `failed` when it denies access): only
+ * system store, `unavailable` when it cannot be reached, `failed` when the
+ * user denies access): only
  * those codes get the "could not be saved" message, anything else (a
  * missing `secrets` capability) is a bug and is thrown on.
  * ```ts

package/dist/plugin/services.js

@@ -413,7 +413,8 @@ export function system(scope) {
  * too long. Values are 1–1024 bytes counted in UTF-8, so the check uses
  * `Buffer.byteLength`; `secrets.set` would refuse other values with
  * `invalid`. The store itself can still refuse (`unsupported` without a
- * system store, `unavailable` or `failed` when it denies access): only
+ * system store, `unavailable` when it cannot be reached, `failed` when the
+ * user denies access): only
  * those codes get the "could not be saved" message, anything else (a
  * missing `secrets` capability) is a bug and is thrown on.
  * ```ts

package/dist/plugin/testing.js

@@ -3080,7 +3080,7 @@ export class TestHost {
             this.secrets.set(name, String(p.value));
         },
         "secrets.delete": (p) => void this.secrets.delete(String(p.name)),
-        // As the player (host/src/session_storage.rs).
+        // As the player (src/host/src/session_storage.rs).
         "storage.session.get": (p) => {
             const key = sessionKey(p.key);
             return this.sessionStorage.has(key)