@vestra-player/sdk 1.5.30 → 1.5.33

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.5.33
+
+1.5.32 was not published (a tag error).
+
+**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.
+
+- **Five more categories reach the full reference standard** and join `STRICT_CATEGORIES`: Subtitles (`Subtitles` and its state and track types), Sources (`Resolvers`, `Resolver` and the resolver option and result types), Media (`MediaCapture`, `Snapshot`, `ExportJob` and their options), Processing (`VideoFilter`, `AudioFilter`, `VideoView`, `RenderOptions` and the node and settings types) and Packages (`Packages`, `PackageCandidate`, `PackageChange` and the manifest and plugin-info types); `Bindings` joins Commands, `Timeline` and `TimelineLayer` join Playback, `Drops` joins UI. Every method has an example (what it does and how it works), `@capability`, `@since` and a `@throws` per error code, checked against the SDK and the player's source; every type has `@category`. Methods with an explained example: 121 of 191 → 153.
+- Facts the reference now states, from the source: an `ExportJob` and a `PackageChange` are polled (about every 350 ms and 400 ms) until they end, and their `done` resolves with a failed outcome rather than rejecting; a plugin holds at most 4 snapshots (16 in the player); `VideoView.set`, `RenderOptions.set` and the filters' `set` never throw (a refusal shows in `status` and goes to `onError`); `Resolver.ready` rejects with `conflict` without failing activation when another plugin holds the extension or host.
+- **The rest reaches the standard: every declaration is now in `STRICT_CATEGORIES`.** Plugin (`Plugin`, `Scope`, `Disposable`, `MainWindow`, `App` and their data types) and Testing (`TestHost`, `startPlugin`, the fakes, `HostError` and the limit and table constants) join the other categories; `doc-lint` now checks declarations of `@vestra-player/sdk/testing` too. Methods with an explained example: 182 of 191; the other 9 are callback fields of option types, documented on the owning type.
+- **Corrections from the review against the player's and the SDK's source.** Subtitles have no event: the SDK reads the subtitle state again on source, phase or backend changes, so a selection changed in the player shows after `refresh()`; a change without `ifCurrent` reads the newest state first and almost never fails with `stale`, and the select example passes `ifCurrent` (embedded tracks are chosen by number). `setStyle` reports a font not in `state.fonts` as `unsupported`. Packages: the player copies a package when it validates it, so `staleDigest` is not a code the SDK sees; a broken package is `host` (with `javascript` and `slint` for code that does not parse or compile), `versionMismatch` only for a newer `minPlayerVersion`; `cancel` of a committed change answers `tooLate` and the change stays `committed`. The Drops example claims `.ch8`: the built-in playlist claims every audio and video extension first. More codes: `missing`, `unavailable` and `busy` for subtitle changes, `busy` (2 exports per plugin, 8 in the player) and `unavailable` for `Snapshot.export`, `busy` and `revisionConflict` for install and uninstall, `busy` (16 resolvers) for `Resolver.ready`, `missing` for `Bindings.reset`, `command` for `FakeCommand.run`; `plugin.video.view()` and `render()` throw `capability` or a plain `Error` for a second handle, and `render()` is `failed` with `unsupported` at once under software rendering.
+- **TestHost follows the player more closely.** A core action run from its menu record (`host.coreAction(id).run()`) while it is disabled now rejects with `command`, like the player (it rejected with `unavailable`, which is what `plugin.host.run` gives). When only disabled commands hold a pressed key, `press` now looks only at the first of them, as the player does: without a `reason` the key passes, even if a later one has a reason. Tests that relied on the old behaviour see a different code or `"passed"`.
+- More corrections from the review: built-in plugins cannot be disabled, so another plugin never gets the built-in playlist's drop extensions or the sequence provider (except a development load replacing the playlist); `validateArchive` reports an archive that cannot be unpacked (over 64 MB, too many files, damaged, unsafe paths) as `invalid` and a broken unpacked package as `host`; `install` is `busy` only while the library is being cleaned up or 64 change records are kept, and `revisionConflict` is retried by calling `install` again; the `PluginError` table no longer lists `staleDigest`, and `versionMismatch` means a newer `minPlayerVersion` only.
+- `llms.txt` may now be 10 KB (10,240 bytes, up from 9 KB) to leave room for about 20 more how-to pages in its index; it stays under 2.6k tokens.
+- New how-to guide: *Load subtitles from a plugin* (reading tracks, selecting with `stale`, uploading SRT/ASS with the limits, the style layer and which plugin's layer the player shows).
+
+## 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/capabilities.d.ts

@@ -4,6 +4,8 @@
  * entry of {@link CAPABILITY_INFO}.
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export interface CapabilityInfo {
     /**
@@ -70,6 +72,8 @@ export interface CapabilityInfo {
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export declare const CAPABILITY_INFO: Readonly<Record<string, CapabilityInfo>>;
 /**
@@ -88,5 +92,7 @@ export declare const API_VERSION = "vestra/1";
  * {@link UI_VALUE_LIMITS} before this.
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export declare const MESSAGE_LIMIT: number;

package/dist/capabilities.js

@@ -34,6 +34,8 @@ import { capabilityInfo } from "./capability-rules.js";
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export const CAPABILITY_INFO = Object.freeze(Object.fromEntries(Object.entries(capabilityInfo()).map(([name, info]) => [
     name,
@@ -60,5 +62,7 @@ export const API_VERSION = "vestra/1";
  * {@link UI_VALUE_LIMITS} before this.
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export const MESSAGE_LIMIT = 1024 * 1024;

package/dist/commands.d.ts

@@ -29,6 +29,9 @@ import type { ListJson, TextJson } from "./i18n.ts";
  * // 20 slots stay free for the plugin's own commands.
  * const shown = chapters.slice(0, Math.min(50, COMMAND_LIMITS.perPlugin - 20));
  * ```
+ *
+ * @since 1.0.0
+ * @category Testing
  */
 export declare const COMMAND_LIMITS: {
     /**
@@ -63,6 +66,9 @@ export declare const COMMAND_LIMITS: {
  * plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run() {} });
  * assert.ok(MENU_IDS.includes("video")); // a menu id, not a title
  * ```
+ *
+ * @since 1.3.0
+ * @category Testing
  */
 export declare const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings"];
 /**
@@ -84,6 +90,8 @@ export declare const MENU_IDS: readonly ["open", "playback", "subtitles", "video
  * ```
  *
  * @since 1.5.29
+ *
+ * @category Testing
  */
 export declare const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back", "forward", "open", "volume", "mute", "playlist", "detach", "attach", "close", "failed", "move-top", "move-up", "move-down", "move-bottom", "search", "chapter", "bookmark", "check-task", "check-box", "menu-check", "submenu", "scroll-up", "scroll-down", "caret-down", "sort-asc", "sort-desc", "tag-remove", "preview-play", "add", "remove", "sort", "fullscreen", "exit-fullscreen", "store", "ai"];
 /**
@@ -97,6 +105,8 @@ export declare const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back"
  * then the earlier declaration, goes first).
  *
  * @since 1.5.29
+ *
+ * @category Testing
  */
 export declare const BAR_BUTTON_LIMITS: {
     /** Buttons one plugin shows (1). */
@@ -111,6 +121,8 @@ export declare const BAR_BUTTON_LIMITS: {
  * {@link BUILTIN_SUBMENUS}.
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export interface BuiltinSubmenu {
     /**
@@ -156,6 +168,8 @@ export interface BuiltinSubmenu {
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export declare const BUILTIN_SUBMENUS: readonly BuiltinSubmenu[];
 /**
@@ -163,6 +177,8 @@ export declare const BUILTIN_SUBMENUS: readonly BuiltinSubmenu[];
  * of {@link BUILTIN_COMMANDS}.
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export interface BuiltinCommand {
     /** `"host"` for the player's own commands, else the built-in plugin's id. */
@@ -208,6 +224,8 @@ export interface BuiltinCommand {
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export declare const BUILTIN_COMMANDS: readonly BuiltinCommand[];
 export type CommandState = {

package/dist/commands.js

@@ -26,6 +26,9 @@
  * // 20 slots stay free for the plugin's own commands.
  * const shown = chapters.slice(0, Math.min(50, COMMAND_LIMITS.perPlugin - 20));
  * ```
+ *
+ * @since 1.0.0
+ * @category Testing
  */
 export const COMMAND_LIMITS = {
     /**
@@ -60,6 +63,9 @@ export const COMMAND_LIMITS = {
  * plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run() {} });
  * assert.ok(MENU_IDS.includes("video")); // a menu id, not a title
  * ```
+ *
+ * @since 1.3.0
+ * @category Testing
  */
 export const MENU_IDS = [
     "open",
@@ -89,6 +95,8 @@ export const MENU_IDS = [
  * ```
  *
  * @since 1.5.29
+ *
+ * @category Testing
  */
 export const BAR_BUTTON_ICONS = [
     "play",
@@ -141,6 +149,8 @@ export const BAR_BUTTON_ICONS = [
  * then the earlier declaration, goes first).
  *
  * @since 1.5.29
+ *
+ * @category Testing
  */
 export const BAR_BUTTON_LIMITS = {
     /** Buttons one plugin shows (1). */
@@ -183,6 +193,8 @@ export const BAR_BUTTON_LIMITS = {
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export const BUILTIN_SUBMENUS = Object.freeze([
     { path: ["Open", "Recently Played"], plugins: ["vestra.history"] },
@@ -584,6 +596,8 @@ vestra.playlist | playlist.settings | (Playlist Settings…) | F5 | panel
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export const BUILTIN_COMMANDS = Object.freeze(BUILTIN_COMMAND_TABLE.trim()
     .split("\n")

package/dist/i18n.d.ts

@@ -3,6 +3,9 @@ import type { ListStyle, Locale } from "./plugin/types.ts";
  * The player's interface languages: English (the source language) first,
  * then the translations, as the player's own table (its tests check that
  * they agree).
+ *
+ * @since 1.5.9
+ * @category Testing
  */
 export declare const LOCALES: readonly ["en", "zh-Hans", "ja", "ko", "de", "fr", "es"];
 /** One message of a `.po` file (the header `msgid ""` is not one). */
@@ -94,6 +97,9 @@ export declare const LIST_STYLES: readonly ListStyle[];
 /**
  * The separator of each list style per interface language, as the player's
  * table (`i18n::text::SEPARATORS`; its tests check that they agree).
+ *
+ * @since 1.5.11
+ * @category Testing
  */
 export declare const LIST_SEPARATORS: Readonly<Record<Locale, Readonly<Record<ListStyle, string>>>>;
 /**
@@ -101,6 +107,9 @@ export declare const LIST_SEPARATORS: Readonly<Record<Locale, Readonly<Record<Li
  * {@link @vestra-player/sdk!Text | Text} or
  * {@link @vestra-player/sdk!TextList | TextList} with everything nested in it), as the player's
  * `i18n::text` (its tests check that they agree).
+ *
+ * @since 1.5.11
+ * @category Testing
  */
 export declare const TEXT_LIMITS: {
     /** Nesting depth of texts and lists; the value itself is depth 0 (8). */

package/dist/i18n.js

@@ -14,6 +14,9 @@ import { join } from "node:path";
  * The player's interface languages: English (the source language) first,
  * then the translations, as the player's own table (its tests check that
  * they agree).
+ *
+ * @since 1.5.9
+ * @category Testing
  */
 export const LOCALES = ["en", "zh-Hans", "ja", "ko", "de", "fr", "es"];
 /** The catalog key: `msgid`, or `msgctxt` U+0004 `msgid`. */
@@ -359,6 +362,9 @@ export const LIST_STYLES = [
 /**
  * The separator of each list style per interface language, as the player's
  * table (`i18n::text::SEPARATORS`; its tests check that they agree).
+ *
+ * @since 1.5.11
+ * @category Testing
  */
 export const LIST_SEPARATORS = {
     en: {
@@ -416,6 +422,9 @@ export const LIST_SEPARATORS = {
  * {@link @vestra-player/sdk!Text | Text} or
  * {@link @vestra-player/sdk!TextList | TextList} with everything nested in it), as the player's
  * `i18n::text` (its tests check that they agree).
+ *
+ * @since 1.5.11
+ * @category Testing
  */
 export const TEXT_LIMITS = {
     /** Nesting depth of texts and lists; the value itself is depth 0 (8). */

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

@@ -33,5 +33,7 @@
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export declare const THEME_PALETTES: Readonly<Record<"vestra" | "vestra-light", Readonly<Record<string, string>>>>;

package/dist/palettes.js

@@ -33,6 +33,8 @@
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export const THEME_PALETTES = Object.freeze({
     vestra: Object.freeze({

package/dist/plugin/bindings.d.ts

@@ -44,6 +44,8 @@ import type { Bindings } from "./types.ts";
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export declare const BINDING_INPUTS: Readonly<{
     /**

package/dist/plugin/bindings.js

@@ -51,6 +51,8 @@ import { failure } from "./runtime.js";
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export const BINDING_INPUTS = Object.freeze({
     /**

package/dist/plugin/osd.d.ts

@@ -29,6 +29,8 @@ import type { TemplateArgsJson, TextValueJson } from "../wire.ts";
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export declare const OSD_LIMITS: Readonly<{
     /**

package/dist/plugin/osd.js

@@ -30,6 +30,8 @@ import { isTextValue, textProblem } from "../i18n.js";
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export const OSD_LIMITS = Object.freeze({
     /**

package/dist/plugin/services.d.ts

@@ -41,6 +41,8 @@ export declare function tools(scope: ScopeImpl): Tools;
  * ```
  *
  * @since 1.5.25
+ *
+ * @category Testing
  */
 export declare const SESSION_STORAGE_LIMITS: Readonly<{
     /** UTF-8 bytes of a key (1024, at least 1; no NUL character). */
@@ -69,7 +71,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
@@ -94,6 +97,8 @@ export declare function system(scope: ScopeImpl): System;
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export declare const SECRET_LIMITS: Readonly<{
     /**

package/dist/plugin/services.js

@@ -275,6 +275,8 @@ class Store {
  * ```
  *
  * @since 1.5.25
+ *
+ * @category Testing
  */
 export const SESSION_STORAGE_LIMITS = Object.freeze({
     /** UTF-8 bytes of a key (1024, at least 1; no NUL character). */
@@ -413,7 +415,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
@@ -438,6 +441,8 @@ export function system(scope) {
  * ```
  *
  * @since 1.5.14
+ *
+ * @category Testing
  */
 export const SECRET_LIMITS = Object.freeze({
     /**