@vestra-player/sdk 1.5.49 → 1.5.51

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.5.51
+
+**Who must change: nobody.** Additive: `MENU_IDS` and `MenuId` gain `reset`, `apiVersion` stays `vestra/1`, no new capability. A plugin that puts a command under `@reset` sets `"minPlayerVersion": "0.6.3"`: older players refuse `@reset` with `invalid` (since SDK 1.5.49 that command is skipped and the rest of the plugin activates).
+
+- **A Reset menu for every reset-to-default command** (user ruling, 2026-11-01). `["@reset", "Picture"]` (or the key `["Reset", …]`) puts a command into the player's new built-in top-level menu **Reset**, directly below Settings and in Settings' separator group (order 840, whatever the groups of the items inside). It lists the resets of every plugin in one place, so users do not hunt for them through Video, Audio and Subtitles; like every built-in menu it is shown only once a command is in it, and its title is the player's (复位 in Simplified Chinese).
+- **`BUILTIN_COMMANDS` lists the built-in plugins' resets under Reset**, as player 0.6.3 declares them (command ids and default keys unchanged): `Reset ▸ Subtitle Position` (`move-reset`, Alt+Home), `Reset ▸ Subtitle Sync` (`sync-reset`, /), `Reset ▸ Picture` (`video.reset`, Q), `Reset ▸ Framing` (`video.frame.reset`, Numpad5, Alt+Backspace), `Reset ▸ Crop Position` (`video.reframe.reset`), `Reset ▸ Audio Sync` (`audio.sync.reset`, ?), `Reset ▸ Audio Processing` (`audio.reset`, now the processing only) and `Reset ▸ Idle Logo` (`reset-logo`, was `Settings ▸ Appearance ▸ Restore Default Logo`). `BUILTIN_SUBMENUS` is unchanged: every submenu these left keeps other items. The built-in command table in [Reference: commands](docs/reference/commands.md) follows.
+- **`TestHost`** accepts `@reset`, shows Reset in the player's words (`HOST_ZH_HANS`) and lists it in its refusal of an unknown menu id (`… @settings, @reset`).
+- _Docs_: [Guidelines: menus](docs/guidelines/menus.md#reset) gains **Reset**: put reset-to-default commands under `@reset`, titled by what they reset, without the word Reset ("Picture", "Subtitle Sync"); order and group them by domain; keep the command id when moving one (bindings and the user's keys follow the id); a "Normal"/"Default" radio or clearing user data is not a reset. [Reference: commands](docs/reference/commands.md#built-in-menus) lists `@reset` and the top-level sketch shows it; `CommandOptions.order` gives its fixed order.
+
+## 1.5.50
+
+**Who must change: tools that read `llms-full.txt`.** It is removed (approved by the maintainer, 2026-11-01): from the package (`@vestra-player/sdk/llms-full.txt`), from the documentation site and from the generators. Read the documentation tree instead: `npx -p @vestra-player/sdk vestra-plugin docs [path]` and `… docs --search <words>`, or `docs(path)` and `searchDocs(query)` from `@vestra-player/sdk/docs` in a program. The player's Workshop vendors the package's `dist/` (the tree is `dist/docs-tree.json.gz`, built with the package; reading it needs nothing else) and must drop its `llms-full.txt` expectation. Plugins need no change: no changes to the plugin API, `apiVersion` stays `vestra/1`, no new capability, no player version needed.
+
+- **The documentation as a tree for agents** (`@vestra-player/sdk/docs`, `vestra-plugin docs`). An agent never gets one large file any more (`llms-full.txt` was 1,032 KiB, half of it the API type dump, too large for an agent to read): it reads the documentation by path, like `go doc`, with the same pages, structure and text as the site. `/` lists Overview (the README), Guides and API; `/Guides/<group>/<page>` is a page of the site (`/Guides/How-to/Test a plugin`; its file name, with or without `.md`, and an old title work too); `/API/<category>/<symbol>/<member>` is one declaration of `@vestra-player/sdk`, `@vestra-player/sdk/testing` or `@vestra-player/sdk/docs` with its import line, signature (and links to the SDK types it names), parameters, return value, errors, capability, minimum player version, since and examples (`/API/Media/Snapshot/dispose`). Every node lists the paths one level down with the site's one-line summary (a page's description, a declaration's first paragraph). Links in the text are paths of the tree (in angle brackets when they have spaces), including the README's links to the site; other repository files link to GitHub; images are left out.
+- **Paths are forgiving.** Case, spaces and punctuation do not matter, the leading `/` is optional, `.` works like `/` (`Snapshot.export`, `plugin.player`), a name alone finds its node at any depth (`TestHost`, `TestHost/settle`; a declaration wins over a guide page of a similar name and an interface over a category of the same name), one stale segment is left out (`/API/Playback/Snapshot/export`), and the whole path is tried against every candidate (`/API/Media/current` finds the interface `Media`'s member, not the category). Several equally good matches are listed, not guessed; a path that matches nothing answers with the nearest names and the level's contents. `#heading` opens the page of a long answer that has the section. In Git Bash, `vestra-plugin docs` undoes the shell's conversion of `/API…` into a Windows path (detected by `MSYSTEM`).
+- **Search** (`searchDocs(query)`, `--search`) lists the nodes containing every word, leaving out common words ("a", "the", "to"); names rank first, a declaration's before a page's, a path that contains every word first of all.
+- **Bounded answers.** Every answer is at most 8 KB (`DOCS_PAGE_BYTES`); a longer one comes in pages (`{ page: 2 }`, `--page 2`). Page 1 lists the sections with the page each starts on; a code block cut by a break is closed and opened again, a short one moves to the next page whole, a cut table repeats its header row.
+- **Built with the package.** `npm run build` (and so `prepare`) converts the project with TypeDoc exactly as the site does (typedoc.json, `scripts/typedoc-plugin.mjs`) and writes `dist/docs-tree.json.gz` (scripts/docs-tree.mjs): 1,137 nodes, about 372 KiB gzipped (1.4 MiB of JSON), read on first use; TypeDoc is needed only to build it. A test checks that every page and every declaration of the site is in the tree, as a node or described in its owner's text.
+- **`llms.txt` is a short entry** (llmstxt.org): what the SDK is, how to read the tree by command line or library, the path scheme, and the tree's top levels with their summaries; about 5 KB, generated from the tree (`npm run docs:llms`).
+- _Docs_: new how-to [Give a coding agent the documentation](docs/how-to/agent-docs.md); [Command line](docs/reference/cli.md) lists `vestra-plugin docs`; the API pages gain `@vestra-player/sdk/docs`; the README and the maintainers' notes point to the tree instead of `llms-full.txt`.
+
 ## 1.5.49
 
 **Who must change: nobody.** No changes to the plugin API (`@vestra-player/sdk/runtime` gains the additive `RuntimeOptions` and an optional sixth `createPlugin` argument), `apiVersion` stays `vestra/1`, no new capability, no player version needed, and the player's runner needs no change. **Behaviour change, approved by the maintainer (2026-11-01):** in the player, a command declaration it refuses during activation no longer fails the whole plugin. What `commands.add` checks itself (an unknown `@` menu id, more than 8 path segments, an `order` out of range, a malformed or repeated binding, a bad `button`, a reason text of the wrong shape) still throws from `add`. A plugin whose `activate` relied on that failure (none is known) now runs without the refused command.

package/README.md

@@ -23,7 +23,7 @@
 - **Tests without the player**: `@vestra-player/sdk/testing` runs your plugin against an in-memory host with `node --test`.
 - **One command line tool**, `vestra-plugin`, to check, test, build and pack a `.vxp` package.
 - **The same API on macOS and Windows**; every plugin runs in its own Node.js 26 process that the player ships.
-- **A reference for AI assistants**: [`llms.txt`](https://vestrasys.github.io/vestra-player-sdk/llms.txt) (short index) and [`llms-full.txt`](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt) (every declaration, the guides and the examples), also in the package as `@vestra-player/sdk/llms.txt` and `@vestra-player/sdk/llms-full.txt`.
+- **Documentation for coding agents**: `npx -p @vestra-player/sdk vestra-plugin docs [path]` reads this documentation as a tree of short pages, like `go doc` (`… docs Snapshot.export`, `… docs --search <words>`; in a project that depends on the SDK, `npx vestra-plugin docs`); programs import `@vestra-player/sdk/docs`. [`llms.txt`](https://vestrasys.github.io/vestra-player-sdk/llms.txt) (also `@vestra-player/sdk/llms.txt`) is the short entry that explains it.
 
 ## Install
 

package/bin/vestra-plugin.mjs

@@ -6,6 +6,8 @@
  *   vestra-plugin <check|build|test|pack> [plugin-dir...] [--version x.y.z] [--out dir]
  *   vestra-plugin i18n extract [plugin-dir...] [--locale <lang>]...
  *   vestra-plugin i18n check [plugin-dir...]
+ *   vestra-plugin docs [path] [--page N]
+ *   vestra-plugin docs --search <query> [--page N]
  *
  * A plugin directory holds manifest.json; the default is the current
  * directory. Works in any project that depends on @vestra-player/sdk.
@@ -19,6 +21,10 @@
  *   test    node --test on tests/*.test.{ts,mjs}
  *   pack    build, then dist/ → <out>/<id>-<version>.vxp (a zip; default
  *           out: the current directory) with its sha256 and size
+ *   docs    the SDK's documentation by path, for coding agents: `/` lists
+ *           Overview, Guides and API, `/API/Media/Snapshot/dispose` is
+ *           one member's whole documentation; --search <query> lists
+ *           matching paths; at most 8 KB per answer, --page N for the rest
  *
  * Translations (docs/how-to/i18n.md). English is the source text; each
  * language is a gettext file locales/<lang>.po:
@@ -932,8 +938,44 @@ const USAGE = [
   "       vestra-plugin check [plugin-dir...] --json",
   "       vestra-plugin i18n extract [plugin-dir...] [--locale <lang>]...",
   "       vestra-plugin i18n check [plugin-dir...]",
+  "       vestra-plugin docs [path] [--page N]",
+  "       vestra-plugin docs --search <query> [--page N]",
 ].join("\n");
 
+/** `vestra-plugin docs`: `@vestra-player/sdk/docs` on the command line. */
+async function docsCommand(args) {
+  const index = args.indexOf("--page");
+  let page;
+  if (index >= 0) {
+    const [, value] = args.splice(index, 2);
+    page = Number(value);
+    if (!Number.isInteger(page) || page < 1)
+      fail("--page needs a page number (1, 2, …)");
+  }
+  const { docs, searchDocs } = await import(
+    pathToFileURL(join(sdkRoot, "dist/docs.js")).href
+  );
+  const search = args.indexOf("--search");
+  if (search >= 0) {
+    args.splice(search, 1);
+    if (!args.length) fail("--search needs words to search for");
+    console.log(searchDocs(args.join(" "), { page }));
+    return;
+  }
+  // A path with spaces may come as several arguments.
+  let path = args.length ? args.join(" ") : "/";
+  // Git Bash (MSYSTEM) turns "/API/Media" into "<its root>/API/Media":
+  // start again at the tree's top level.
+  if (process.env.MSYSTEM && /^[A-Za-z]:[\\/]/.test(path)) {
+    const segments = path.split(/[\\/]/);
+    const top = segments.findIndex((segment) =>
+      ["overview", "guides", "api"].includes(segment.toLowerCase()),
+    );
+    if (top > 0) path = `/${segments.slice(top).join("/")}`;
+  }
+  console.log(docs(path, { page }));
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const command = args.shift();
@@ -948,6 +990,10 @@ async function main() {
     console.log(USAGE);
     return;
   }
+  if (command === "docs") {
+    await docsCommand(args);
+    return;
+  }
   let subcommand = null;
   if (command === "i18n") {
     subcommand = args.shift();

package/dist/commands.d.ts

@@ -98,8 +98,11 @@ export declare const COMMAND_LIMITS: {
  * command into that menu whatever language the player's menus are in. The
  * player stores the menu's title (视频 today); later segments are titles.
  * Needs player 0.3.0 (`"minPlayerVersion": "0.3.0"`); older players show
- * `@video` as a menu of its own. The player's tests check that this list
- * agrees with the player's.
+ * `@video` as a menu of its own. `reset` (SDK 1.5.51) needs player 0.6.3:
+ * the Reset menu, directly below Settings, gathers every command that puts
+ * something back to its default; older players refuse `@reset` with
+ * `invalid`. The player's tests check that this list agrees with the
+ * player's.
  *
  * @example Put a command into the built-in Video menu
  * "Blur" appears in the player's Video menu in every interface language.
@@ -121,7 +124,7 @@ export declare const COMMAND_LIMITS: {
  * @since 1.3.0
  * @category Testing
  */
-export declare const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings"];
+export declare const MENU_IDS: readonly ["open", "playback", "subtitles", "video", "audio", "screen", "settings", "reset"];
 /**
  * The icons a bottom-bar button may name (`CommandOptions.button.icon`):
  * every icon of the player's V-Line set, `@vestra/icons.slint` (draw one

package/dist/commands.js

@@ -94,8 +94,11 @@ export const COMMAND_LIMITS = {
  * command into that menu whatever language the player's menus are in. The
  * player stores the menu's title (视频 today); later segments are titles.
  * Needs player 0.3.0 (`"minPlayerVersion": "0.3.0"`); older players show
- * `@video` as a menu of its own. The player's tests check that this list
- * agrees with the player's.
+ * `@video` as a menu of its own. `reset` (SDK 1.5.51) needs player 0.6.3:
+ * the Reset menu, directly below Settings, gathers every command that puts
+ * something back to its default; older players refuse `@reset` with
+ * `invalid`. The player's tests check that this list agrees with the
+ * player's.
  *
  * @example Put a command into the built-in Video menu
  * "Blur" appears in the player's Video menu in every interface language.
@@ -125,6 +128,7 @@ export const MENU_IDS = [
     "audio",
     "screen",
     "settings",
+    "reset",
 ];
 /**
  * The icons a bottom-bar button may name (`CommandOptions.button.icon`):
@@ -402,13 +406,11 @@ vestra.subtitles | size-up | Subtitles ▸ Subtitle Style ▸ Size + | Alt+PageU
 vestra.subtitles | size-down | Subtitles ▸ Subtitle Style ▸ Size − | Alt+PageDown
 vestra.subtitles | move-up | Subtitles ▸ Subtitle Style ▸ Move Up
 vestra.subtitles | move-down | Subtitles ▸ Subtitle Style ▸ Move Down
-vestra.subtitles | move-reset | Subtitles ▸ Subtitle Style ▸ Reset Position | Alt+Home
 vestra.subtitles | shadow | Subtitles ▸ Subtitle Style ▸ Shadow
 vestra.subtitles | box | Subtitles ▸ Subtitle Style ▸ Opaque Box
 vestra.subtitles | ass-original | Subtitles ▸ Original ASS/SSA Styles
 vestra.subtitles | sync-earlier | Subtitles ▸ Sync ▸ Earlier 0.5 s | .
 vestra.subtitles | sync-later | Subtitles ▸ Sync ▸ Later 0.5 s | ,
-vestra.subtitles | sync-reset | Subtitles ▸ Sync ▸ Reset | /
 vestra.subtitles | sync-input | Subtitles ▸ Sync ▸ Adjust Sync…
 vestra.subtitle-online | search | Subtitles ▸ Online Subtitles ▸ Search and Download Subtitles…
 vestra.subtitle-online | settings | Subtitles ▸ Online Subtitles ▸ Online Subtitle Settings…
@@ -458,12 +460,10 @@ vestra.video | video.reframe.crop.1 | Video ▸ Crop/Stretch ▸ Crop to 16:9
 vestra.video | video.reframe.crop.2 | Video ▸ Crop/Stretch ▸ Crop to 16:10
 vestra.video | video.reframe.crop.3 | Video ▸ Crop/Stretch ▸ Crop to 1.85:1
 vestra.video | video.reframe.crop.4 | Video ▸ Crop/Stretch ▸ Crop to 2.35:1
-vestra.video | video.reframe.reset | Video ▸ Crop/Stretch ▸ Reset Position
 vestra.video | video.reframe.left | Video ▸ Crop/Stretch ▸ Move Left
 vestra.video | video.reframe.right | Video ▸ Crop/Stretch ▸ Move Right
 vestra.video | video.reframe.up | Video ▸ Crop/Stretch ▸ Move Up
 vestra.video | video.reframe.down | Video ▸ Crop/Stretch ▸ Move Down
-vestra.video | video.frame.reset | Video ▸ Framing ▸ Reset Framing | Numpad5, Alt+Backspace
 vestra.video | video.frame.zoom-in | Video ▸ Framing ▸ Zoom In | Numpad9, Alt+Plus
 vestra.video | video.frame.zoom-out | Video ▸ Framing ▸ Zoom Out | Numpad1, Alt+-
 vestra.video | video.frame.right | Video ▸ Framing ▸ Pan → | Ctrl+Numpad6, Alt+ArrowRight
@@ -505,7 +505,6 @@ vestra.capture | capture.settings | Video ▸ Snapshot ▸ Snapshot Settings…
 vestra.capture | capture.folder | Video ▸ Snapshot ▸ Snapshot Folder…
 vestra.capture | capture.openFolder | Video ▸ Snapshot ▸ Open Snapshot Folder
 vestra.video | video.picture | Video ▸ Picture Adjustments…
-vestra.video | video.reset | Video ▸ Reset | Q
 vestra.video | video.brightness.down | Video ▸ Brightness -1% | W
 vestra.video | video.brightness.up | Video ▸ Brightness +1% | E
 vestra.video | video.contrast.down | Video ▸ Contrast -1% | R
@@ -534,13 +533,11 @@ vestra.audio | audio.preset.2 | Audio ▸ Preset ▸ Music
 vestra.audio | audio.preset.3 | Audio ▸ Preset ▸ Cinema
 vestra.audio | audio.sync.earlier | Audio ▸ Audio Sync ▸ 50 ms Earlier | >
 vestra.audio | audio.sync.later | Audio ▸ Audio Sync ▸ 50 ms Later | <
-vestra.audio | audio.sync.reset | Audio ▸ Audio Sync ▸ Reset | ?
 vestra.audio | audio.sync.keep.none | Audio ▸ Audio Sync ▸ Don't Keep
 vestra.audio | audio.sync.keep.session | Audio ▸ Audio Sync ▸ Keep for This Run
 vestra.audio | audio.sync.keep.always | Audio ▸ Audio Sync ▸ Always Keep
 vestra.audio | audio.normalize | Audio ▸ Processing ▸ Normalize | Shift+N
 vestra.audio | audio.clarity | Audio ▸ Processing ▸ Crystalizer | Shift+C
-vestra.audio | audio.reset | Audio ▸ Reset
 vestra.visualizer | audio-cover | Audio ▸ Show Album Cover for Audio Only
 host | fullscreen | Toggle Fullscreen | Escape
 vestra.window | pip | Screen ▸ Picture-in-Picture
@@ -575,7 +572,6 @@ vestra.preferences | theme.vestra | Settings ▸ Appearance ▸ Vestra Dark
 vestra.preferences | theme.vestra-light | Settings ▸ Appearance ▸ Vestra Light
 vestra.visualizer | idle-logo | Settings ▸ Appearance ▸ Show Logo When Idle
 vestra.visualizer | choose-logo | Settings ▸ Appearance ▸ Choose Logo Image…
-vestra.visualizer | reset-logo | Settings ▸ Appearance ▸ Restore Default Logo
 vestra.preferences | language.system | Settings ▸ Language ▸ Follow System
 vestra.preferences | language.en | Settings ▸ Language ▸ English
 vestra.preferences | language.zh-Hans | Settings ▸ Language ▸ 简体中文
@@ -584,6 +580,14 @@ vestra.preferences | language.ko | Settings ▸ Language ▸ 한국어
 vestra.preferences | language.de | Settings ▸ Language ▸ Deutsch
 vestra.preferences | language.fr | Settings ▸ Language ▸ Français
 vestra.preferences | language.es | Settings ▸ Language ▸ Español
+vestra.subtitles | move-reset | Reset ▸ Subtitle Position | Alt+Home
+vestra.subtitles | sync-reset | Reset ▸ Subtitle Sync | /
+vestra.video | video.reset | Reset ▸ Picture | Q
+vestra.video | video.frame.reset | Reset ▸ Framing | Numpad5, Alt+Backspace
+vestra.video | video.reframe.reset | Reset ▸ Crop Position
+vestra.audio | audio.sync.reset | Reset ▸ Audio Sync | ?
+vestra.audio | audio.reset | Reset ▸ Audio Processing
+vestra.visualizer | reset-logo | Reset ▸ Idle Logo
 vestra.info | info.about | About Vestra Player… | F1
 host | quit | Quit | Cmd+Q
 host | enter-fullscreen | (Enter Fullscreen)

package/dist/docs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The most bytes (UTF-8) one answer of `docs` or `searchDocs` has.
+ *
+ * @category Docs
+ */
+export declare const DOCS_PAGE_BYTES = 8192;
+/**
+ * Which page of a long answer to return.
+ *
+ * @category Docs
+ */
+export interface DocsOptions {
+    /** 1-based; the default is 1. */
+    page?: number;
+}
+/**
+ * The documentation at `path`: its text, then the paths one level down,
+ * each with a one-line summary.
+ *
+ * `/` lists Overview, Guides and API. `/Guides/<group>/<page title>` is a
+ * page of the documentation site (its file name works too:
+ * `/Guides/How-to/testing`); `/API/<category>/<symbol>/<member>` is a
+ * declaration with its signature, parameters, return value, errors,
+ * capability, player version and examples. Matching ignores case, spaces
+ * and punctuation; a leading `/` and a `.md` suffix are optional; `.`
+ * works like `/` (`Snapshot.export`); a name that is not at its level is
+ * looked up below it (`TestHost`, `/API/Snapshot` finds
+ * `/API/Media/Snapshot`), and one stale segment is skipped. A `#heading`
+ * opens the page of a long answer that has it. A path that matches
+ * nothing answers with the nearest names and the level's contents.
+ *
+ * @param path - Default `/`.
+ * @param options - `page` of a long answer.
+ * @returns At most {@link DOCS_PAGE_BYTES} bytes of text; a continued
+ *   answer ends with the number of the next page.
+ *
+ * @category Docs
+ */
+export declare function docs(path?: string, options?: DocsOptions): string;
+/**
+ * Search the documentation by name and text: the matching paths, best
+ * first, each with its one-line summary. Every word of `query` (common
+ * words such as "a", "the", "to" left out) must occur, in any case, in
+ * the path, the summary or the text; a match in a name ranks first, a
+ * declaration's name before a page's.
+ *
+ * @param query - Words, such as `"snapshot export"` or `"onError"`.
+ * @param options - `page` of a long answer.
+ * @returns At most {@link DOCS_PAGE_BYTES} bytes of text.
+ *
+ * @category Docs
+ */
+export declare function searchDocs(query: string, options?: DocsOptions): string;