@vestra-player/sdk 1.5.49 → 1.5.51

package/llms.txt

@@ -1,148 +1,42 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.49: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process (the player's built-in plugins share one). Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
+> @vestra-player/sdk 1.5.51: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
 
-**Rules**
+## Read the documentation
 
-- **Only the public SDK.** Import `@vestra-player/sdk` with `import type` only (a runtime import fails `vestra-plugin build`) and `@vestra-player/sdk/testing` only in tests.
-- **No other plugins.** Do not import another plugin's code, read its directory or data directory, or talk to it privately (shared files, sockets, messages).
-- **No system commands.** Do not run `open`, `sips`, `plutil`, `security`, `cmd`, `powershell` or similar.
-- **macOS and Windows.** The same code runs on both: build paths with `node:path`, write package paths with `/`, and handle `unsupported` where a method documents a platform difference.
-- **Your own id.** `<owner>.<name>`, where the owner is your GitHub user or organization.
+- **Command line** (any coding agent): `npx -p @vestra-player/sdk vestra-plugin docs [path] [--page N]` prints one node of the tree; `npx -p @vestra-player/sdk vestra-plugin docs --search <words>` lists the matching paths. In a project that depends on the SDK, `npx vestra-plugin docs` is enough.
+- **In a Node.js program**: `import { docs, searchDocs } from "@vestra-player/sdk/docs"`; `docs(path, { page })` and `searchDocs(query, { page })` return the same text.
+- **Paths**: `/` lists the top level; every answer lists the paths one level down with a one-line summary. `/API/<category>/<symbol>/<member>` is one declaration with its signature, parameters, return value, errors, capability, player version and examples, for example `/API/Media/Snapshot/dispose`. `/Guides/<group>/<page>` is a page of the site, for example `/Guides/How-to/Test a plugin` (the file name works too: `/Guides/How-to/testing`). Case, spaces and punctuation do not matter, the leading `/` is optional, `.` works like `/`, a name alone finds its declaration (`TestHost`, `Snapshot.export`, `plugin.player`), and `#heading` opens the page of a long answer that has that section.
+- **Size**: every answer is at most 8 KB; a longer one ends with the number of its next page (`--page 2`).
+- **Before writing code**, read `/Guides/Tutorials/Getting started` and `/Guides/Guidelines`, then the API of what you use. Test with `/Guides/How-to/Test a plugin`.
 
-**Files**
+## Top level
 
-```text
-my-plugin/
-  manifest.json        identity and capabilities
-  main.ts              the entry module
-  ui/hello.slint       optional: user interface
-  tests/main.test.ts   tests (node:test)
-  package.json         dev dependency and scripts
-```
+- `/Overview`: The package's README: what the SDK is, installing it and where to start.
+- `/Guides`: The documentation pages, by group: tutorials, how-to guides, reference, explanation, guidelines, examples, upgrading.
+- `/API`: Every type and value of @vestra-player/sdk (the plugin API), @vestra-player/sdk/testing (the test host) and @vestra-player/sdk/docs (this tree), by category.
 
-**manifest.json**
+## Guides
 
-```json
-{
-  "id": "me.hello",
-  "version": "0.1.0",
-  "apiVersion": "vestra/1",
-  "entry": "main.ts",
-  "capabilities": ["commands", "ui.osd", "playback.read", "events"]
-}
-```
-
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2218–2292.
-
-**main.ts**
-
-```ts
-import type { Plugin } from "@vestra-player/sdk";
-
-export default async function activate(plugin: Plugin) {
-  plugin.commands.add({
-    id: "hello",
-    path: ["Tools", "Hello"],
-    run: () => plugin.osd.show("Hello"),
-  });
-}
-```
-
-**Capabilities** (without one a call fails: `capability`)
-
-- `producer.av`: Player.openStream (also `playback.control`)
-- `playback.read`: Player.state/refresh/stats/chapters/audioDevices, Timeline.marks
-- `playback.control`: Player.open/setPaused/seek/setRate/restart/close/scrub/setOutput/provideSequence/next/previous/addAudioTrack/selectAudioTrack/step/setStepSeek/setLoop/setAudioDevice, Power.preventSleep
-- `source.resolve`: Resolvers.add
-- `events`: Player/Subtitles/Timeline/MainWindow/Appearance/PanelSlot/Panel/BackdropSlot.onChange, Resolvers.onFileTypesChange
-- `commands`: Commands.add, Host.run
-- `ui.window`: Windows.create
-- `ui.mount`: Panels.mount/bottom/sidebar/backdrop, PanelSlot/Panel/BackdropSlot.onChange
-- `ui.dialog`: Dialogs.confirm/openFile/openFiles/openDirectory/saveFile
-- `plugins.manage`: Packages.validate/validateArchive/setEnabled/reload/uninstall
-- `processing.video`: Plugin.video.filter/video.view/video.render/video.shaders (also `playback.read`)
-- `processing.audio`: Plugin.audio.filter (also `playback.read`, `events`)
-- `subtitles.read`: Subtitles.state/onChange/refresh
-- `subtitles.control`: Subtitles.select/load/remove/setStyle
-- `media.read`: MediaCapture.capture, Snapshot.export (also `media.control`)
-- `media.control`: MediaCapture.capture, Snapshot.export (also `media.read`)
-- `ui.osd`: Osd.show/panel
-- `clipboard`: Clipboard.readText/writeText/writeImage
-- `window.control`: MainWindow.setVideoArea/setAlwaysOnTop/setCursorAutoHide/setPictureInPicture
-- `bindings.manage`: Bindings.list/set/reset/onChange
-- `timeline.marks`: Timeline.layer
-- `ui.drop`: Drops.provide, Panel.onDrop
-- `ui.settings`: Settings.page/show
-- `ui.theme`: Appearance.set/setLanguage
-- `secrets`: Secrets.get/set/delete
-- `rendering.manage`: Rendering.setPreference/restartPlayer
-- `video.upscaling`: VideoUpscaling.state/set/onChange
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2293–2353.
-
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L1861–2021; TestHost: L15530.
-
-**Command line**
-
-- `vestra-plugin check`: strict type check of the plugin's .ts files and tests/*.ts
-- `vestra-plugin build`: check, then write dist/
-- `vestra-plugin test`: node --test on tests/*.test.{ts,mjs}
-- `vestra-plugin pack`: build, then dist/ → <out>/<id>-<version>.vxp
-- `vestra-plugin i18n extract`: find the texts to translate, write locales/messages.pot and merge it into every locales/<lang>.po
-- `vestra-plugin i18n check`: coverage per language, placeholder and plural problems, a stale messages.pot
-- `vestra-player --plugin <dir>` runs a plugin from source, no build needed.
-
-**Error codes** (`error.code`; branch on it, never on `message`)
-
-- `stale`: A condition no longer held
-- `capability`: The manifest does not declare the capability the call needs
-- `invalid`: A bad argument
-- `missing`: The target does not exist
-- `busy`: The player is still doing a previous call of the same kind
-- `conflict`: Another plugin owns the resource
-- `unavailable`: Not possible right now
-- `unsupported`: Not possible on this system, build or source
-- `failed`: The operation ran and failed
-- `aborted`: An `AbortSignal` fired
-- `timeout`: A time limit ran out
-- `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
-- `reserved`: The id is `vestra` or starts with `vestra.`
-- `versionMismatch`: The package needs a newer player
-- Others: PluginError, llms-full.txt L5972.
-
-## Reference
-
-- [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; pages: [site](https://vestrasys.github.io/vestra-player-sdk/).
-- Tutorials: Getting started L9–134; Add a window L135–213; Add settings and translations L214–367; Test, check, pack and publish L368–424; Write your own blur kernel L425–685
-- How-to: Control playback L686–854; Store a plugin's data L855–961; Load subtitles from a plugin L962–1074; Keep a slider responsive while dragging L1075–1262; Remember a window's state between runs L1263–1414; Offer a GPU rendering switch L1415–1540; Keep a command's state without keeping the plugin running L1541–1697; Translate a plugin L1698–1860; Test a plugin L1861–2021; Publish a plugin L2022–2123; Troubleshooting L2124–2217
-- Reference: Manifest L2218–2292; Capabilities L2293–2353; Limits L2354–2506; Commands, menus and bindings L2507–3033; Platforms L3034–3064; Theme L3065–3414; Command line L3415–3472; Error codes L3473–3520; Translations L3521–3613; Test host L3614–3800
-- Explanation: How a plugin runs L3801–4007; Commands, menus and key bindings L4008–4162; Playback state, controls and sources L4163–4322; Video and audio processing L4323–4443; Windows, panels, settings pages, dialogs and the OSD L4444–4708; GPU and software rendering L4709–4725; The player's Rust core L4726–5067; How the player runs and talks to plugins L5068–5407
-- Guidelines: Plugin rules L5408–5419; Interface guidelines L5420–5537; Menu guidelines L5538–5596
-- Upgrading: Migrate a plugin to English source text L5597–5746; Migrating off package rollback (1.5.16, removed in 1.5.17) L5747–5824; Who must change, release by release L5825–5894
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5895–15203
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15204–18090
+- `/Guides/Tutorials`: Step-by-step lessons; the first four build one plugin, from an empty folder to a tested package in the plugin store.
+- `/Guides/How-to`: Short guides that each answer one practical question about writing, translating, testing or publishing a plugin.
+- `/Guides/Reference`: Lookup tables that span many symbols (capabilities, manifest fields and player versions, limits, menu and binding names, platform differences, theme, command line), generated from the SDK's code.
+- `/Guides/Explanation`: What each part of the player and its plugins is, why it works the way it does and how the parts fit together.
+- `/Guides/Guidelines`: The rules a plugin follows so that its windows, panels, messages and menu items look and behave like the rest of Vestra Player.
+- `/Guides/Examples`: Complete, tested example plugins with a screenshot each and a step-by-step walkthrough of their code.
+- `/Guides/Upgrading`: What to change in a plugin when an SDK or player release deprecates, removes or changes something it uses.
 
 ## API
 
-Where each `plugin.<module>` is declared:
-
-- Plugin L6311, Scope L6047, PluginError L5972, Disposable L5910
-- Commands L6927; When L6502; Windows L7875; Panels L9321; Dialogs L9991; Player L10732; video: VideoFilter L11612, VideoView L11712, RenderOptions L11799, VideoShaders L11877, VideoUpscaling L12235; audio: AudioFilter L11657; Subtitles L12471; media: MediaCapture L12875; Resolvers L13105; Packages L13507; Osd L11477; Host L11319; Clipboard L13836; Power L13923; Tools L13982; Storage L14134; System L14333; Secrets L14413; window: MainWindow L9638; App L9818; Rendering L14676; Bindings L13735; Ui L7221; Timeline L9550; Drops L8568; Appearance L8649; I18n L8882; Settings L9165.
-
-## Examples
-
-Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
-
-- hello: The README Quick start: one menu command and an on-screen message. L18525–18620
-- blur: A tool window with one slider that blurs the playing video. L18621–18888
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18889–19227
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19228–19420
-- panel-menu: A sidebar panel with its own right-click menu. L19421–19635
-- menus: Radio menu items, separator groups and a menu item whose title changes. L19636–19801
-- theme-widgets: A tool window drawn with the player's theme and widgets. L19802–19971
-- markdown: A window that shows a Markdown document. L19972–20174
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L20175–20348
-
-## Optional
-
-- [Changelog](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md); full doc comments in the package's dist/plugin/*.d.ts; Slint library in slint/vestra/.
+- `/API/Commands`: 15 entries: CommandState, Bindable, Condition, When, MenuId, BarButtonIcon, CommandButton, CommandOptions, Command, Commands, HostAction, Host, BindingRef, BindingInfo, Bindings
+- `/API/Media`: 6 entries: CaptureOptions, Snapshot, ExportOptions, JobState, ExportJob, MediaCapture
+- `/API/Packages`: 10 entries: PackageManifest, PackageSource, InstallOptions, PackageCandidate, PackageChangeStatus, PackageChange, PluginInfo, PluginDisplay, PluginWarning, Packages
+- `/API/Playback`: 18 entries: MarkKind, TimelineMark, TimelineLayer, Timeline, AudioTrack, PlayerState, AudioDevice, Chapter, Conditional, Media, Scrub, StreamFrame, StreamOptions, StreamStartError, Stream,…
+- `/API/Plugin`: 11 entries: Disposable, PluginError, Scope, Plugin, WindowState, MainWindow, AppInfo, App, SystemInfo, DisplayInfo, Json
+- `/API/Processing`: 18 entries: FilterStatus, VideoFilter, AudioFilter, ViewSettings, VideoView, RenderSettings, RenderOptions, VideoShaders, UpscalingReasonCode, UpscalingReason, UpscalingDecodingCause,…
+- `/API/Services`: 15 entries: Clipboard, Power, ToolResult, Tools, JsonStore, Storage, SessionStorage, System, Secrets, RenderingMode, RenderingPreference, RenderingReasonCode, RenderingReason, RenderingState,…
+- `/API/Sources`: 7 entries: ResolverOptions, WebResolverOptions, FileResolverOptions, ResolvedStream, Resolver, Resolvers, ResolvedMedia
+- `/API/Subtitles`: 5 entries: SubtitleTrack, SubtitlesState, SubtitleConditional, Subtitles, SubtitleStyle
+- `/API/UI`: 42 entries: ImageRef, ImageOptions, MarkdownRef, MarkdownOptions, PropValue, PropData, Props, Ui, View, Window, Windows, SlotState, SlotPanel, PanelState, PanelSlot, SidebarSlot, Panel,…
+- `/API/Testing`: 32 entries: CapabilityInfo, CAPABILITY_INFO, MESSAGE_LIMIT, COMMAND_LIMITS, MENU_IDS, BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BuiltinSubmenu, BUILTIN_SUBMENUS, BuiltinCommand, BUILTIN_COMMANDS, LOCALES,…
+- `/API/Docs`: 4 entries: DOCS_PAGE_BYTES, DocsOptions, docs, searchDocs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.49",
+  "version": "1.5.51",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {
@@ -24,12 +24,15 @@
       "types": "./dist/player-runtime.d.ts",
       "default": "./dist/player-runtime.js"
     },
+    "./docs": {
+      "types": "./dist/docs.d.ts",
+      "default": "./dist/docs.js"
+    },
     "./ts-plugin": {
       "types": "./ts-plugin/index.d.ts",
       "default": "./ts-plugin/index.js"
     },
     "./llms.txt": "./llms.txt",
-    "./llms-full.txt": "./llms-full.txt",
     "./package.json": "./package.json"
   },
   "bin": {
@@ -43,8 +46,7 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
-    "llms.txt",
-    "llms-full.txt"
+    "llms.txt"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",