@vestra-player/sdk 1.5.29 → 1.5.31

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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.
+
+- **Every example explains what it does and how it works.** The standard, in *Maintaining* ("Examples in reference comments"): an `@example` has a task title, a lead saying what it does and how it works (checked against the SDK and the player's source), code that compiles on its own with comments on the key lines, and error handling where the user can make a call fail. All 159 examples of the API now meet it (none did before this release), including the 65 of the UI category, the test helpers (`TestHost`, `startPlugin`, `HostError`), the limits and tables (`COMMAND_LIMITS`, `MENU_IDS`, `BUILTIN_*`, `BAR_BUTTON_ICONS`, `CAPABILITY_INFO`, `BINDING_INPUTS`, `OSD_LIMITS`, `SESSION_STORAGE_LIMITS`, `SECRET_LIMITS`, `UI_VALUE_LIMITS`, `THEME_PALETTES`) and the 1.5.29 bar buttons (`CommandButton`, `TestHost.barButtons`). Every example now type checks (61 did not). Examples no longer compose shown sentences in TypeScript: OSD and dialog texts are templates with arguments.
+- **Corrections found on the way.** `Subtitles.setStyle`, `SubtitlesState.style` and `SubtitleStyle`: when several plugins set a style layer, the effective one is the layer of the plugin whose manifest id sorts last, not the latest call. `COMMAND_LIMITS`: `add` never throws `limit`; the player refuses the registration (activation fails, or `Scope.onError`). `startPlugin`'s restart example gives both runs the same `dataDirectory` instead of copying the data before `stop()` (which could miss a pending store write). `TestHost.settle` says the debounced store write is not waited for. `TestHost.dialogAnswers` is one queue for every kind of dialog. `TestHost.openElsewhere`: calls that return nothing (`TimelineLayer.set` with `ifCurrent`) drop the write silently instead of rejecting. Resolver examples (`I18n.error`, `FileResolverOptions`, `TestHost.otherResolvers`) use a made-up `.ch8` format instead of `.nes`, which the store plugin VestraNES owns.
+- **`llms-full.txt` carries the examples and `@remarks`** of every declaration and member (hidden setup lines dropped, `{@includeCode}` inlined), so the plugin workshop's model sees them: 536 KB → 693 KB (about 137k → 177k tokens). `llms.txt` wording trimmed to stay under its 9 KB limit (9,134 bytes).
+- **Hidden setup lines**: in an `@example` code block, lines above `// ---cut---` are type checked but not shown on the site or in `llms-full.txt`.
+- **Checks.** `docs:check` fails on any block that does not compile (it only warned for most examples; `--lenient` keeps the old behaviour for work in progress). `doc-lint` gains `example-lead` (task title, lead, comments, one `// ---cut---` at most; `See` markers for trivial siblings, whose link must resolve, at most 20 % of a declaration's methods) and `stale-refs` (removed or handed-over names such as `vestra.nes`, `.nes` resolvers), enforced for every example and Markdown code block, and prints per category the share of methods with an explained example. `EXAMPLE_BASELINE` keeps known violations per problem when a rule is tightened; it is empty, and `test/doc-baseline.test.ts` keeps it from growing.
+- The parts of `examples/bookmark`, `examples/markdown` and `examples/panel-menu` that the reference includes gained comments on their key lines.
+- Test only: the storage test in `test/round2.test.ts` waits for the debounced file to appear and for `flush()` instead of a fixed 60 ms, and stops its plugins before removing their data directory, so it no longer fails now and then with `ENOENT` on a loaded machine.
+
 ## 1.5.29
 
 **Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. A plugin that does not use `button` is unaffected. A plugin that uses it on a player before 0.5.10 keeps working without a button: the player builds the `plugin` object with its own SDK copy, which does not send the field, so the command and its menu entry register as before (declare `"minPlayerVersion": "0.5.10"` when the button matters). A plugin that mounts its own bottom bar should place `BarButtons` (below); until it does, `vestra-plugin check` warns and the player logs the buttons it hides.

package/dist/capabilities.d.ts

@@ -49,13 +49,23 @@ export interface CapabilityInfo {
  * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
  * and `plugin.packages.list`).
  *
- * @example
+ * @example Check in a test that the manifest declares every required capability
+ * The test fails, naming the missing capability, when the manifest declares
+ * a capability without one its members also need. It reads the plugin's own
+ * `manifest.json` and looks each declared name up in `CAPABILITY_INFO`,
+ * whose `requires` lists the capabilities that must be declared with it;
+ * at run time the player would refuse such a call with code `capability`.
  * ```ts
+ * import assert from "node:assert/strict";
+ * import { readFile } from "node:fs/promises";
  * import { CAPABILITY_INFO } from "@vestra-player/sdk/testing";
  *
- * const manifest = JSON.parse(await readFile("manifest.json", "utf8"));
+ * const manifest: { capabilities: string[] } = JSON.parse(
+ *   await readFile(new URL("../manifest.json", import.meta.url), "utf8"),
+ * );
  * for (const capability of manifest.capabilities)
- *   for (const needed of CAPABILITY_INFO[capability].requires)
+ *   // An unknown name has no entry: `vestra-plugin check` reports it.
+ *   for (const needed of CAPABILITY_INFO[capability]?.requires ?? [])
  *     assert.ok(manifest.capabilities.includes(needed), needed);
  * ```
  *

package/dist/capabilities.js

@@ -13,13 +13,23 @@ import { capabilityInfo } from "./capability-rules.js";
  * `plugin.i18n`, reading `plugin.window.state`, `plugin.appearance.theme`
  * and `plugin.packages.list`).
  *
- * @example
+ * @example Check in a test that the manifest declares every required capability
+ * The test fails, naming the missing capability, when the manifest declares
+ * a capability without one its members also need. It reads the plugin's own
+ * `manifest.json` and looks each declared name up in `CAPABILITY_INFO`,
+ * whose `requires` lists the capabilities that must be declared with it;
+ * at run time the player would refuse such a call with code `capability`.
  * ```ts
+ * import assert from "node:assert/strict";
+ * import { readFile } from "node:fs/promises";
  * import { CAPABILITY_INFO } from "@vestra-player/sdk/testing";
  *
- * const manifest = JSON.parse(await readFile("manifest.json", "utf8"));
+ * const manifest: { capabilities: string[] } = JSON.parse(
+ *   await readFile(new URL("../manifest.json", import.meta.url), "utf8"),
+ * );
  * for (const capability of manifest.capabilities)
- *   for (const needed of CAPABILITY_INFO[capability].requires)
+ *   // An unknown name has no entry: `vestra-plugin check` reports it.
+ *   for (const needed of CAPABILITY_INFO[capability]?.requires ?? [])
  *     assert.ok(manifest.capabilities.includes(needed), needed);
  * ```
  *

package/dist/commands.d.ts

@@ -4,18 +4,29 @@ import type { ListJson, TextJson } from "./i18n.ts";
 /**
  * The player's command registry caps, the same values as the player's own
  * table (the player's tests check that they agree). They are runaway guards,
- * not product limits: a command added past them fails with code `limit`
- * (its `ready` rejects; during activation, activation fails), commands
+ * not product limits: a command added past them is refused by the player
+ * with code `limit` (its `ready` rejects; during activation, activation
+ * fails; later the failure goes to `Scope.onError`), commands
  * already registered are unaffected, and disposing a command frees its slot
  * at once. {@link TestHost} enforces the same caps.
  *
  * For menus built from media content (tracks, chapters, presets), set your
  * own sensible display cap well below `perPlugin`.
  *
- * @example
+ * @example Cap a chapter menu well below the command limit
+ * The Chapters submenu lists at most 50 chapters, however many the file
+ * has. Every menu item is a command, and the player counts them per plugin.
+ * `add` itself returns at once and never throws `limit`: past `perPlugin`
+ * the player refuses the registration, which fails the activation or, later,
+ * reaches `Scope.onError`. A try/catch around `add` cannot catch that, so a
+ * menu built from media content keeps its own cap and leaves room for the
+ * plugin's fixed commands.
  * ```ts
+ * declare const chapters: { title: string; time: number }[];
+ * // ---cut---
  * import { COMMAND_LIMITS } from "@vestra-player/sdk/testing";
  *
+ * // 20 slots stay free for the plugin's own commands.
  * const shown = chapters.slice(0, Math.min(50, COMMAND_LIMITS.perPlugin - 20));
  * ```
  */
@@ -36,11 +47,21 @@ export declare const COMMAND_LIMITS: {
  * `@video` as a menu of its own. The player's tests check that this list
  * agrees with the player's.
  *
- * @example
+ * @example Put a command into the built-in Video menu
+ * "Blur" appears in the player's Video menu in every interface language.
+ * The player replaces a leading `@video` with that menu's key ("Video")
+ * before it merges paths, so the item joins the built-in menu; an id that
+ * is not in `MENU_IDS` makes `add` fail with `invalid`, which a test can
+ * rule out ahead of time.
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * // ---cut---
+ * import assert from "node:assert/strict";
  * import { MENU_IDS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(MENU_IDS.includes("video"));
+ * plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run() {} });
+ * assert.ok(MENU_IDS.includes("video")); // a menu id, not a title
  * ```
  */
 export declare const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings"];
@@ -50,12 +71,16 @@ export declare const MENU_IDS: readonly ["open", "playback", "subtitles", "video
  * in your own Slint with `Icon { name: "store"; }`). The player's tests check
  * that this list is its icon set.
  *
- * @example
+ * @example Check in a test that the button's icon exists
+ * The test fails before release if the plugin's bar button names an icon
+ * the player does not have. `commands.add` would refuse an unknown name
+ * with `invalid`; the player's tests keep `BAR_BUTTON_ICONS` equal to its
+ * icon set, so checking against it is the same check without a player.
  * ```ts
  * import assert from "node:assert/strict";
  * import { BAR_BUTTON_ICONS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(BAR_BUTTON_ICONS.includes("store"));
+ * assert.ok(BAR_BUTTON_ICONS.includes("store")); // the icon main.ts uses
  * ```
  *
  * @since 1.5.29
@@ -108,13 +133,23 @@ export interface BuiltinSubmenu {
  * listed. The player's tests check that this list agrees with what its
  * built-in plugins declare.
  *
- * @example
+ * @example Add an item to the built-in Snapshot submenu
+ * "Copy Snapshot" appears in Video ▸ Snapshot next to the built-in capture
+ * plugin's items. Paths merge by their English keys, so a command whose
+ * path continues with the submenu's keys (`["Video", "Snapshot"]`, the menu
+ * written as `@video`) lands in the same submenu whatever the interface
+ * language.
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare function copySnapshot(): Promise<void>;
+ * // ---cut---
  * import { BUILTIN_SUBMENUS } from "@vestra-player/sdk/testing";
  *
  * const snapshot = BUILTIN_SUBMENUS.find((menu) => menu.path.at(-1) === "Snapshot")!;
  * plugin.commands.add({
  *   id: "snapshot-to-clipboard",
+ *   // ["@video", "Snapshot", "Copy Snapshot"]; @video stands for "Video".
  *   path: ["@video", ...snapshot.path.slice(1), "Copy Snapshot"],
  *   run: copySnapshot,
  * });
@@ -157,7 +192,12 @@ export interface BuiltinCommand {
  * placeholders (`No Audio Tracks`) are. The player's tests check that this
  * list agrees with what the player and its built-in plugins register.
  *
- * @example
+ * @example Check in a test that a default key is still free
+ * The test fails if the player or a built-in plugin already binds Ctrl+K
+ * globally, before users ever see a conflict. It collects the default
+ * bindings of every built-in command that is not limited to its panel's
+ * focus (`focus: null`) and looks for the key the plugin wants; bindings
+ * are canonical, so compare them as the player writes them.
  * ```ts
  * import assert from "node:assert/strict";
  * import { BUILTIN_COMMANDS } from "@vestra-player/sdk/testing";

package/dist/commands.js

@@ -1,18 +1,29 @@
 /**
  * The player's command registry caps, the same values as the player's own
  * table (the player's tests check that they agree). They are runaway guards,
- * not product limits: a command added past them fails with code `limit`
- * (its `ready` rejects; during activation, activation fails), commands
+ * not product limits: a command added past them is refused by the player
+ * with code `limit` (its `ready` rejects; during activation, activation
+ * fails; later the failure goes to `Scope.onError`), commands
  * already registered are unaffected, and disposing a command frees its slot
  * at once. {@link TestHost} enforces the same caps.
  *
  * For menus built from media content (tracks, chapters, presets), set your
  * own sensible display cap well below `perPlugin`.
  *
- * @example
+ * @example Cap a chapter menu well below the command limit
+ * The Chapters submenu lists at most 50 chapters, however many the file
+ * has. Every menu item is a command, and the player counts them per plugin.
+ * `add` itself returns at once and never throws `limit`: past `perPlugin`
+ * the player refuses the registration, which fails the activation or, later,
+ * reaches `Scope.onError`. A try/catch around `add` cannot catch that, so a
+ * menu built from media content keeps its own cap and leaves room for the
+ * plugin's fixed commands.
  * ```ts
+ * declare const chapters: { title: string; time: number }[];
+ * // ---cut---
  * import { COMMAND_LIMITS } from "@vestra-player/sdk/testing";
  *
+ * // 20 slots stay free for the plugin's own commands.
  * const shown = chapters.slice(0, Math.min(50, COMMAND_LIMITS.perPlugin - 20));
  * ```
  */
@@ -33,11 +44,21 @@ export const COMMAND_LIMITS = {
  * `@video` as a menu of its own. The player's tests check that this list
  * agrees with the player's.
  *
- * @example
+ * @example Put a command into the built-in Video menu
+ * "Blur" appears in the player's Video menu in every interface language.
+ * The player replaces a leading `@video` with that menu's key ("Video")
+ * before it merges paths, so the item joins the built-in menu; an id that
+ * is not in `MENU_IDS` makes `add` fail with `invalid`, which a test can
+ * rule out ahead of time.
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * // ---cut---
+ * import assert from "node:assert/strict";
  * import { MENU_IDS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(MENU_IDS.includes("video"));
+ * plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run() {} });
+ * assert.ok(MENU_IDS.includes("video")); // a menu id, not a title
  * ```
  */
 export const MENU_IDS = [
@@ -55,12 +76,16 @@ export const MENU_IDS = [
  * in your own Slint with `Icon { name: "store"; }`). The player's tests check
  * that this list is its icon set.
  *
- * @example
+ * @example Check in a test that the button's icon exists
+ * The test fails before release if the plugin's bar button names an icon
+ * the player does not have. `commands.add` would refuse an unknown name
+ * with `invalid`; the player's tests keep `BAR_BUTTON_ICONS` equal to its
+ * icon set, so checking against it is the same check without a player.
  * ```ts
  * import assert from "node:assert/strict";
  * import { BAR_BUTTON_ICONS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(BAR_BUTTON_ICONS.includes("store"));
+ * assert.ok(BAR_BUTTON_ICONS.includes("store")); // the icon main.ts uses
  * ```
  *
  * @since 1.5.29
@@ -135,13 +160,23 @@ export const BAR_BUTTON_LIMITS = {
  * listed. The player's tests check that this list agrees with what its
  * built-in plugins declare.
  *
- * @example
+ * @example Add an item to the built-in Snapshot submenu
+ * "Copy Snapshot" appears in Video ▸ Snapshot next to the built-in capture
+ * plugin's items. Paths merge by their English keys, so a command whose
+ * path continues with the submenu's keys (`["Video", "Snapshot"]`, the menu
+ * written as `@video`) lands in the same submenu whatever the interface
+ * language.
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare function copySnapshot(): Promise<void>;
+ * // ---cut---
  * import { BUILTIN_SUBMENUS } from "@vestra-player/sdk/testing";
  *
  * const snapshot = BUILTIN_SUBMENUS.find((menu) => menu.path.at(-1) === "Snapshot")!;
  * plugin.commands.add({
  *   id: "snapshot-to-clipboard",
+ *   // ["@video", "Snapshot", "Copy Snapshot"]; @video stands for "Video".
  *   path: ["@video", ...snapshot.path.slice(1), "Copy Snapshot"],
  *   run: copySnapshot,
  * });
@@ -533,7 +568,12 @@ vestra.playlist | playlist.settings | (Playlist Settings…) | F5 | panel
  * placeholders (`No Audio Tracks`) are. The player's tests check that this
  * list agrees with what the player and its built-in plugins register.
  *
- * @example
+ * @example Check in a test that a default key is still free
+ * The test fails if the player or a built-in plugin already binds Ctrl+K
+ * globally, before users ever see a conflict. It collects the default
+ * bindings of every built-in command that is not limited to its panel's
+ * focus (`focus: null`) and looks for the key the plugin wants; bindings
+ * are canonical, so compare them as the player writes them.
  * ```ts
  * import assert from "node:assert/strict";
  * import { BUILTIN_COMMANDS } from "@vestra-player/sdk/testing";

package/dist/index.d.ts

@@ -12,7 +12,12 @@
  * documents the manifest capability it needs. Errors are described at
  * {@link PluginError}. Tests use `@vestra-player/sdk/testing`.
  *
- * @example
+ * @example Add a menu item that shows a message
+ * The player gets a Tools ▸ Hello menu item; picking it shows "Hello" on
+ * the video. The player imports the entry module and calls `activate` with
+ * the plugin's `Plugin` object; `commands.add` registers the item (manifest
+ * capability `commands`), and the player calls `run` when the user picks it
+ * or presses a key bound to it. `osd.show` needs `ui.osd`.
  * ```ts
  * import type { Plugin } from "@vestra-player/sdk";
  *

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

@@ -11,11 +11,25 @@
  * the palette (`slint/palette.slint`); the player's tests check both
  * palettes against its own.
  *
- * @example
+ * @example Check in a test that a colour stays readable in both themes
+ * The test fails if the plugin's own highlight colour gets too close to
+ * the panel background of either palette. Plugins draw with `Theme` tokens
+ * in Slint and the player switches palettes; a colour the plugin picks
+ * itself does not switch, so a test compares it with each palette's values
+ * (hex strings, `#rrggbb`).
  * ```ts
+ * import assert from "node:assert/strict";
  * import { THEME_PALETTES } from "@vestra-player/sdk/testing";
  *
- * const accent = THEME_PALETTES["vestra-light"].accent; // "#d4128a"
+ * const highlight = "#e07000"; // the plugin's own orange
+ * const luminance = (hex: string) => {
+ *   const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+ *   return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!; // rough, without gamma
+ * };
+ * for (const [name, palette] of Object.entries(THEME_PALETTES)) {
+ *   const gap = Math.abs(luminance(highlight) - luminance(palette["bg-panel"]!));
+ *   assert.ok(gap > 0.3, `${name}: highlight too close to bg-panel`);
+ * }
  * ```
  *
  * @since 1.5.14

package/dist/palettes.js

@@ -11,11 +11,25 @@
  * the palette (`slint/palette.slint`); the player's tests check both
  * palettes against its own.
  *
- * @example
+ * @example Check in a test that a colour stays readable in both themes
+ * The test fails if the plugin's own highlight colour gets too close to
+ * the panel background of either palette. Plugins draw with `Theme` tokens
+ * in Slint and the player switches palettes; a colour the plugin picks
+ * itself does not switch, so a test compares it with each palette's values
+ * (hex strings, `#rrggbb`).
  * ```ts
+ * import assert from "node:assert/strict";
  * import { THEME_PALETTES } from "@vestra-player/sdk/testing";
  *
- * const accent = THEME_PALETTES["vestra-light"].accent; // "#d4128a"
+ * const highlight = "#e07000"; // the plugin's own orange
+ * const luminance = (hex: string) => {
+ *   const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+ *   return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!; // rough, without gamma
+ * };
+ * for (const [name, palette] of Object.entries(THEME_PALETTES)) {
+ *   const gap = Math.abs(luminance(highlight) - luminance(palette["bg-panel"]!));
+ *   assert.ok(gap > 0.3, `${name}: highlight too close to bg-panel`);
+ * }
  * ```
  *
  * @since 1.5.14

package/dist/plugin/bindings.d.ts

@@ -11,12 +11,36 @@ import type { Bindings } from "./types.ts";
  * `"Shift+1"`). Anything else fails with code `invalid`. The player's tests
  * check that these agree with the player.
  *
- * @example
+ * @example Check in a test that the plugin's default keys are well formed
+ * The test fails on a binding the player would refuse with `invalid`, such
+ * as modifiers out of order or a misspelt key name. `isBinding` applies the
+ * same grammar as the player's parser: the part after the last `+` is the
+ * input, everything before it modifiers in the order of `modifiers`; an
+ * input is a listed name or one other printable character, and `Shift`
+ * never goes with a digit or such a character.
  * ```ts
+ * import assert from "node:assert/strict";
  * import { BINDING_INPUTS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(BINDING_INPUTS.named.includes("PageUp"));
- * assert.ok(BINDING_INPUTS.mouse.includes("Mouse:WheelUp"));
+ * const { modifiers, letters, digits, functionKeys, named, mouse } = BINDING_INPUTS;
+ * const names = new Set([...letters, ...functionKeys, ...named, ...mouse]);
+ * function isBinding(binding: string): boolean {
+ *   // "Ctrl++" is not a binding: the + key is written "Plus".
+ *   const parts = binding.split("+");
+ *   const input = parts.pop()!;
+ *   const order = parts.map((m) => (modifiers as readonly string[]).indexOf(m));
+ *   // Each modifier known, at most once, in the listed order.
+ *   if (order.some((at, i) => at < 0 || (i > 0 && at <= order[i - 1]!)))
+ *     return false;
+ *   if (names.has(input)) return true; // letters are upper case: "A"
+ *   const typed = digits.includes(input) || /^[^\p{L}\p{N}\p{C}\s+]$/u.test(input);
+ *   // ">" rather than "Shift+.": the character already says Shift.
+ *   return typed && !parts.includes("Shift");
+ * }
+ * for (const binding of ["Ctrl+Shift+PageUp", "Alt+Mouse:WheelUp", ">"])
+ *   assert.ok(isBinding(binding), binding);
+ * for (const binding of ["Shift+Ctrl+A", "Ctrl+a", "Shift+."])
+ *   assert.ok(!isBinding(binding), binding);
  * ```
  *
  * @since 1.5.14

package/dist/plugin/bindings.js

@@ -18,12 +18,36 @@ import { failure } from "./runtime.js";
  * `"Shift+1"`). Anything else fails with code `invalid`. The player's tests
  * check that these agree with the player.
  *
- * @example
+ * @example Check in a test that the plugin's default keys are well formed
+ * The test fails on a binding the player would refuse with `invalid`, such
+ * as modifiers out of order or a misspelt key name. `isBinding` applies the
+ * same grammar as the player's parser: the part after the last `+` is the
+ * input, everything before it modifiers in the order of `modifiers`; an
+ * input is a listed name or one other printable character, and `Shift`
+ * never goes with a digit or such a character.
  * ```ts
+ * import assert from "node:assert/strict";
  * import { BINDING_INPUTS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(BINDING_INPUTS.named.includes("PageUp"));
- * assert.ok(BINDING_INPUTS.mouse.includes("Mouse:WheelUp"));
+ * const { modifiers, letters, digits, functionKeys, named, mouse } = BINDING_INPUTS;
+ * const names = new Set([...letters, ...functionKeys, ...named, ...mouse]);
+ * function isBinding(binding: string): boolean {
+ *   // "Ctrl++" is not a binding: the + key is written "Plus".
+ *   const parts = binding.split("+");
+ *   const input = parts.pop()!;
+ *   const order = parts.map((m) => (modifiers as readonly string[]).indexOf(m));
+ *   // Each modifier known, at most once, in the listed order.
+ *   if (order.some((at, i) => at < 0 || (i > 0 && at <= order[i - 1]!)))
+ *     return false;
+ *   if (names.has(input)) return true; // letters are upper case: "A"
+ *   const typed = digits.includes(input) || /^[^\p{L}\p{N}\p{C}\s+]$/u.test(input);
+ *   // ">" rather than "Shift+.": the character already says Shift.
+ *   return typed && !parts.includes("Shift");
+ * }
+ * for (const binding of ["Ctrl+Shift+PageUp", "Alt+Mouse:WheelUp", ">"])
+ *   assert.ok(isBinding(binding), binding);
+ * for (const binding of ["Shift+Ctrl+A", "Ctrl+a", "Shift+."])
+ *   assert.ok(!isBinding(binding), binding);
  * ```
  *
  * @since 1.5.14

package/dist/plugin/osd.d.ts

@@ -8,11 +8,23 @@ import type { TemplateArgsJson, TextValueJson } from "../wire.ts";
  * rejects, `OsdPanel.set` reports to `Scope.onError`. The player's tests
  * check that these agree with the player.
  *
- * @example
+ * @example Keep a long list inside the information block's limits
+ * The block shows the first 32 rows of a list, each cut at 60 columns. The
+ * player counts the text as shown (after it is translated and formatted); a
+ * block over `panelLines` lines or `panelBytes` bytes is refused whole with
+ * `invalid`, reported to `Scope.onError` because `set` never throws, so
+ * the plugin trims the list itself (for very long non-ASCII rows, check the
+ * bytes too).
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const rows: string[];
+ * // ---cut---
  * import { OSD_LIMITS } from "@vestra-player/sdk/testing";
  *
+ * const panel = plugin.osd.panel();
  * const lines = rows.slice(0, OSD_LIMITS.panelLines);
+ * // maxColumns cuts each longer line and ends it with "…".
  * panel.set(lines.join("\n"), null, { maxColumns: 60 });
  * ```
  *

package/dist/plugin/osd.js

@@ -9,11 +9,23 @@ import { isTextValue, textProblem } from "../i18n.js";
  * rejects, `OsdPanel.set` reports to `Scope.onError`. The player's tests
  * check that these agree with the player.
  *
- * @example
+ * @example Keep a long list inside the information block's limits
+ * The block shows the first 32 rows of a list, each cut at 60 columns. The
+ * player counts the text as shown (after it is translated and formatted); a
+ * block over `panelLines` lines or `panelBytes` bytes is refused whole with
+ * `invalid`, reported to `Scope.onError` because `set` never throws, so
+ * the plugin trims the list itself (for very long non-ASCII rows, check the
+ * bytes too).
  * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const rows: string[];
+ * // ---cut---
  * import { OSD_LIMITS } from "@vestra-player/sdk/testing";
  *
+ * const panel = plugin.osd.panel();
  * const lines = rows.slice(0, OSD_LIMITS.panelLines);
+ * // maxColumns cuts each longer line and ends it with "…".
  * panel.set(lines.join("\n"), null, { maxColumns: 60 });
  * ```
  *

package/dist/plugin/services.d.ts

@@ -13,13 +13,31 @@ export declare function tools(scope: ScopeImpl): Tools;
  * with the key and the request around the value). The player's tests check
  * that these agree with the player.
  *
- * @example
+ * @example Remember a position per URL without breaking the limits
+ * The plugin keeps the last position of each URL for this player session
+ * and skips a URL too long to be a key. Keys are counted in UTF-8 bytes, so
+ * the length is measured with `Buffer.byteLength`, not `length`; a `set`
+ * that would take the plugin's entries over 1 MiB rejects with `limit` and
+ * changes nothing, so the plugin clears the old entries and goes on.
  * ```ts
- * import assert from "node:assert/strict";
+ * import type { Plugin, PluginError } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const url: string;
+ * declare const position: number;
+ * // ---cut---
  * import { SESSION_STORAGE_LIMITS } from "@vestra-player/sdk/testing";
  *
- * const key = "https://example.com/a.mkv";
- * assert.ok(Buffer.byteLength(key) <= SESSION_STORAGE_LIMITS.keyBytes);
+ * const session = plugin.storage.session;
+ * if (Buffer.byteLength(url) <= SESSION_STORAGE_LIMITS.keyBytes) {
+ *   try {
+ *     await session.set(url, position);
+ *   } catch (error) {
+ *     if ((error as PluginError).code !== "limit") throw error;
+ *     // Full: start over rather than lose the newest position.
+ *     for (const key of await session.keys()) await session.delete(key);
+ *     await session.set(url, position);
+ *   }
+ * }
  * ```
  *
  * @since 1.5.25
@@ -46,11 +64,34 @@ export declare function system(scope: ScopeImpl): System;
  * fails with code `invalid`; a new name beyond `names` fails with `limit`.
  * The player's tests check that these agree with the player.
  *
- * @example
+ * @example Store an API token only when it fits
+ * The plugin keeps a token the user pasted, or tells them it is empty or
+ * 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` 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
+ * import type { Plugin, PluginError } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const token: string;
+ * // ---cut---
  * import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(Buffer.byteLength(token) <= SECRET_LIMITS.valueBytes);
+ * if (!token || Buffer.byteLength(token) > SECRET_LIMITS.valueBytes) {
+ *   await plugin.osd.show("Paste a token of at most 1024 bytes.");
+ * } else {
+ *   try {
+ *     await plugin.secrets.set("api-token", token);
+ *   } catch (error) {
+ *     const { code } = error as PluginError;
+ *     if (!["unsupported", "unavailable", "failed"].includes(code)) throw error;
+ *     // No keychain or access denied: ask again next time.
+ *     await plugin.osd.show("The token could not be saved.");
+ *   }
+ * }
  * ```
  *
  * @since 1.5.14